How aasawari-m10/health-insurance-policy-advisor works
This repository implements a health-insurance policy advisor with a FastAPI interface and MCP tools. The main question workflow classifies intent, resolves a policy version, checks safety constraints, retrieves plan-scoped clauses, generates an answer, and validates it. A separate comparison workflow retrieves evidence for two policies and produces a structured comparison. The graph includes document access and key Azure services; several relationships are omitted because their implementation was not sampled.
Main entry points: advisor_service.py Question workflow · routes.py HTTP API · mcp_server.py MCP tools · comparison_service.py Plan comparison
Components 19
User interfaces
- HTTP API
app/api/routes.py - Application startup
app/main.py - Request schemas
app/schemas.py - MCP tools
app/mcp_server.py - MCP server setup
mcp/server.py
Policy advising
- Question workflow
app/services/advisor_service.py - Intent classifier
app/services/classifier_service.py - Plan versions
app/services/plan_service.py - Safety checks
app/services/guardrail_service.py - Plan comparison
app/services/comparison_service.py
Policy evidence
- Clause retrieval and context
app/services/rag_service.py - Query embeddings
app/services/embedding_service.py - Policy document access
app/services/policy_document_service.py - Blob storage access
app/services/blob_service.py
External services
- Azure AI Search
- Azure OpenAI
- Azure Blob Storage
Other components
- Advisor user
- MCP client
Connections 24
- Advisor user → HTTP API: asks question
app/api/routes.py - Application startup → HTTP API: mounts routes
app/main.py - HTTP API → Request schemas: validates requests
app/api/routes.py - HTTP API → Question workflow: processes question
app/api/routes.py - Question workflow → Intent classifier: classifies intent
app/services/advisor_service.py - Question workflow → Plan versions: resolves version
app/services/advisor_service.py - Question workflow → Safety checks: checks request and answer
app/services/advisor_service.py - Question workflow → Clause retrieval and context: retrieves context
app/services/advisor_service.py - Question workflow → Azure OpenAI: generates answer
- HTTP API → Plan comparison: compares plans
app/api/routes.py - Plan comparison → Clause retrieval and context: retrieves clauses
app/services/comparison_service.py - Plan comparison → Azure OpenAI: generates comparison
- Plan comparison → Safety checks: validates evidence
app/services/comparison_service.py - Clause retrieval and context → Query embeddings: embeds query
app/services/rag_service.py - Clause retrieval and context → Azure AI Search: searches clauses
app/services/rag_service.py - Query embeddings → Azure OpenAI: creates embeddings
- HTTP API → Policy document access: lists or fetches PDFs
app/api/routes.py - Policy document access → Blob storage access: uses storage
app/services/policy_document_service.py - Blob storage access → Azure Blob Storage: reads blobs
- Application startup → MCP tools: mounts MCP server
app/main.py - MCP client → MCP tools: invokes tools
- MCP tools → Clause retrieval and context: searches policy
app/mcp_server.py - MCP tools → Plan comparison: compares policies
app/mcp_server.py - MCP tools → Policy document access: lists documents
app/mcp_server.py