How jaspinxu/insuretutor works
InsureTutor is a bilingual tutor for insurance-plan documents. A user submits a question in the React app; the backend streams a turn through input checks, intent routing, hybrid retrieval, grounded generation (or offline extracts), and answer validation. Citations lead to source passages and PDF pages, while conversations persist for history and follow-ups. The graph includes the documented ingestion and retrieval capabilities. Some subsystem links rely on README descriptions or SOURCE INDEX references; unsampled internals are not expanded.
Main entry points: chat.py Turn orchestrator · base.py LLM interface · App.tsx Chat app · retriever.py Hybrid retriever
Components 25
Chat interface
- Chat app
frontend/src/App.tsx - API client
frontend/src/api.ts - Answer view
frontend/src/components/MessageView.tsx - Source panel
frontend/src/components/SourcePanel.tsx - Localization
frontend/src/i18n.ts
Chat service
- Turn orchestrator
backend/app/chat.py - Grounded prompts
backend/app/prompts.py
Document knowledge
- Hybrid retriever
backend/app/rag/retriever.py - Keyword search
backend/app/rag/bm25.py - Dense embeddings
backend/app/rag/embeddings.py - PDF ingestion
backend/app/ingest/pipeline.py
Safety and language
- Input guard
backend/app/guardrails/input.py - Intent router
backend/app/guardrails/router.py - Answer checks
backend/app/guardrails/output.py - Citation fact check
backend/app/guardrails/verify.py - Language handling
backend/app/lang.py
Runtime services
- HTTP API
backend/app/api/routes.py - Conversation store
backend/app/store.py - Provider selection
backend/app/llm/__init__.py - LLM interface
backend/app/llm/base.py - OpenAI provider
backend/app/llm/openai_provider.py - Anthropic provider
backend/app/llm/anthropic_provider.py
Other components
- Plan reader
- LLM service
- PDF reader
Connections 27
- Plan reader → Chat app: asks question
README.md - Chat app → API client: starts chat
frontend/src/App.tsx - Chat app → Answer view: renders answers
frontend/src/App.tsx - Answer view → Source panel: opens citations
README.md - Chat app → Localization: localizes interface
frontend/src/App.tsx - API client → HTTP API: sends chat request
README.md - HTTP API → Turn orchestrator: dispatches turns
backend/app/api/routes.py - HTTP API → Conversation store: serves history
backend/app/api/routes.py - Turn orchestrator → Input guard: checks input
backend/app/chat.py - Turn orchestrator → Intent router: routes intent
backend/app/chat.py - Turn orchestrator → Hybrid retriever: searches sources
backend/app/chat.py - Turn orchestrator → Grounded prompts: builds grounded prompt
backend/app/chat.py - Turn orchestrator → Answer checks: checks answer
backend/app/chat.py - Turn orchestrator → Citation fact check: verifies claims
backend/app/chat.py - Turn orchestrator → Language handling: detects answer language
backend/app/chat.py - Turn orchestrator → Conversation store: reads and saves turns
backend/app/chat.py - Hybrid retriever → Keyword search: runs keyword search
backend/app/rag/retriever.py - Hybrid retriever → Dense embeddings: uses dense vectors
backend/app/rag/retriever.py - Hybrid retriever → PDF ingestion: loads corpus
backend/app/rag/retriever.py - PDF ingestion → PDF reader: extracts document pages
backend/app/ingest/pipeline.py - Intent router → LLM interface: requests structured route
backend/app/guardrails/router.py - Turn orchestrator → LLM interface: streams answer
backend/app/chat.py - Provider selection → OpenAI provider: selects provider
backend/app/llm/__init__.py - Provider selection → Anthropic provider: selects provider
backend/app/llm/__init__.py - OpenAI provider → LLM interface: implements interface
backend/app/llm/openai_provider.py - Anthropic provider → LLM interface: implements interface
backend/app/llm/anthropic_provider.py - LLM interface → LLM service: calls configured model