Skip to content
Back to search

insurance-claims-analytics

Four-layer insurance claims analytics: LLM summaries, grounded RAG, human-in-the-loop triage agent, MCP servers, document ingestion with OCR, severity ML and governance

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/avinasshkotta--insurance-claims-analytics/badge.svg)](/listings/avinasshkotta--insurance-claims-analytics)

HTML

<a href="/listings/avinasshkotta--insurance-claims-analytics"><img src="/api/listings/avinasshkotta--insurance-claims-analytics/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

cd Insurance-claims-4layer
pip install -r requirements.txt
pip install -e .
Copy-Item .env.example .env     # paste your OPENAI_API_KEY

Run the API (port **8010** — 8000 is often taken on this machine):

python -m uvicorn claims_assistant.api:app --host 127.0.0.1 --port 8010

Run the console (second terminal):

cd frontend
npm install
npm run dev

Open **http://localhost:5173** — triage claims, inspect risk reasons, ask policy questions, and watch the adjuster queue fill. (`npm.ps1` may be blocked by your PowerShell policy; if so use `npm.cmd install` / `npm.cmd run dev`.)

Production build (single origin, UI served by FastAPI):

cd frontend && npm run build
cd ..
python -m uvicorn claims_assistant.api:app --port 8010
# → http://localhost:8010 serves the built UI + API

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 193 lines
  1. # Insurance Claims Analytics — Four-Layer Build-Out
  2. The Insurance Claims capstone run through all four solution layers in order, shipped as a
  3. tested Python service with a React console, an evaluation harness, and a Docker image.
  4. | Layer | What it adds | Module |
  5. |---|---|---|
  6. | 1 · LLM | Plain-language claim verbatim summaries (PII-redacted before the prompt) | `llm.py` |
  7. | 2 · RAG | Policy answers grounded in the retrieved regional document — or refused | `rag.py` |
  8. | 3 · AI Agent | Triage: status → deterministic risk → route flagged claims to a human | `agent.py` + `risk.py` |
  9. | 4 · MCP | Three least-privilege MCP servers behind one client interface | `mcp_*_server.py` |
  10. Specification: [`../case-studies/02-insurance-claims-four-layer-rctc.md`](../case-studies/02-insurance-claims-four-layer-rctc.md)
  11. Process report and interview pack: `docs/`
  12. ## Stack
  13. Python 3.10+ · OpenAI-compatible chat model (function calling) · hosted embeddings +
  14. local vector cache (BM25 fallback) · document ingestion with vision OCR (PDF/DOCX/XLSX/CSV/PNG) · MCP SDK ·
  15. FastAPI · React 18 + Vite 5 · Docker
  16. ## Quick start
  17. ```powershell
  18. cd Insurance-claims-4layer
  19. pip install -r requirements.txt
  20. pip install -e .
  21. Copy-Item .env.example .env # paste your OPENAI_API_KEY
  22. ```
  23. Run the API (port **8010** — 8000 is often taken on this machine):
  24. ```powershell
  25. python -m uvicorn claims_assistant.api:app --host 127.0.0.1 --port 8010
  26. ```
  27. Run the console (second terminal):
  28. ```powershell
  29. cd frontend
  30. npm install
  31. npm run dev
  32. ```
  33. Open **http://localhost:5173** — triage claims, inspect risk reasons, ask policy questions,
  34. and watch the adjuster queue fill. (`npm.ps1` may be blocked by your PowerShell policy;
  35. if so use `npm.cmd install` / `npm.cmd run dev`.)
  36. Production build (single origin, UI served by FastAPI):
  37. ```powershell
  38. cd frontend && npm run build
  39. cd ..
  40. python -m uvicorn claims_assistant.api:app --port 8010
  41. # → http://localhost:8010 serves the built UI + API
  42. ```
  43. ## CLI
  44. ```powershell
  45. python -m pytest -q # 101 tests, no key needed
  46. python -m claims_assistant.cli eval # golden-set regression gate (offline)
  47. python -m claims_assistant.cli eval --live # same, against real model answers
  48. python -m claims_assistant.cli reindex # build the semantic index (embeddings)
  49. python -m claims_assistant.cli ml # train severity model + clusters (synthetic history)
  50. python -m claims_assistant.cli drift # PSI drift report vs training baseline
  51. python -m claims_assistant.cli fairness # segment parity audit
  52. python -m claims_assistant.cli triage # triage all open/under_review claims
  53. python -m claims_assistant.cli triage --via-mcp # same run through the MCP server
  54. python -m claims_assistant.cli ask CLM-1042 "What is the daily rental reimbursement limit?"
  55. ```
  56. ## Document ingestion (unstructured → structured claim)
  57. Upload a **PDF, DOCX, XLSX, CSV, TXT, MD or image (PNG/JPG)** in the console (or
  58. `POST /api/uploads`). Text files are parsed directly; scanned PDFs and images are rendered and
  59. read with **vision OCR**. An extraction agent returns claim JSON, and a deterministic validator
  60. checks types, regions, ISO dates, positive amounts and verbatim length, feeding failures back
  61. for repair (max 3 attempts). Every attempt is traced; if validation still fails, the claim is
  62. saved as **`needs_review`** rather than guessed. Duplicate detection (same type+region, amount
  63. within 5%, incident date within 7 days, matching claimant) also holds a claim for review with
  64. `duplicate_of`.
  65. ```powershell
  66. curl.exe -F "file=@samples/home-claim-intake.pdf" http://127.0.0.1:8010/api/uploads
  67. ```
  68. Sample documents: `samples/home-claim-intake.pdf`, `samples/auto-claim-intake.docx`,
  69. `samples/scanned-claim.pdf` (vision OCR), `samples/claim-photo.png` (vision OCR),
  70. `samples/health-claim-intake.csv`, `samples/claims.xlsx`. See `samples/README.md` for the
  71. expected outcome of each file. Some samples intentionally duplicate existing claims to
  72. demonstrate deduplication.
  73. ## Documentation and walkthrough
  74. - **Executed notebook:** `notebooks/insurance_claims_walkthrough.ipynb` — 24 cells covering
  75. data, RAG, risk, compliance, ingestion/OCR, ML, evaluation, guardrails and tests.
  76. - **Presentation documents** — project guide, process report, interview Q&A and interview pack —
  77. are kept **outside the repository** in `..\Insurance-Claims-Docs\` (see its README). They are
  78. intentionally not committed.
  79. The repo ignores `docs/*.pdf`, `docs/*.html` and `docs/*.png` so presentation artifacts can never
  80. be committed by accident.
  81. ## Docker
  82. ```powershell
  83. docker build -t claims-console .
  84. docker run -d --name claims-console -p 8020:8000 --env-file .env claims-console
  85. # → http://localhost:8020 (UI + API)
  86. ```
  87. The image builds the Vite bundle in a Node stage, installs the Python service, and ships the
  88. trained severity model. `scikit-learn` is pinned to **1.7.2** so the saved joblib bundle loads
  89. (the pickle references private sklearn modules; version drift breaks it). Regenerate the model
  90. inside a different environment with `python -m claims_assistant.cli ml`.
  91. ## Project layout
  92. ```
  93. ├── Dockerfile # multi-stage: Vite build → FastAPI runtime
  94. ├── prompts/ # versioned prompts (summary, rag, triage, ingestion)
  95. ├── eval/golden_set.json # 9 policy Q&A cases + thresholds
  96. ├── samples/ # sample intake documents (text + scanned + image)
  97. ├── notebooks/ # executed walkthrough notebook
  98. ├── docs/ # guide, report, Q&A (PDFs git-ignored)
  99. ├── scripts/make_samples.py # regenerates the sample documents
  100. ├── models/ # trained severity bundle + drift baseline (generated)
  101. ├── data/ # claims, regional policies, case queue (runtime)
  102. ├── src/claims_assistant/
  103. │ ├── llm.py # Layer 1 — summaries, PII redaction, metering
  104. │ ├── rag.py # Layer 2 — filter-first retrieval (hybrid), refuse-or-answer
  105. │ ├── embeddings.py # embedding cache + RRF fusion (BM25 fallback)
  106. │ ├── guardrails.py # injection scan, PII redaction, citation verification
  107. │ ├── risk.py # Layer 3 — 12 weighted, explainable signals
  108. │ ├── agent.py # Layer 3 — tool loop, direct + MCP transports
  109. │ ├── mcp_claims_server.py # Layer 4 — claims DB server (read-only)
  110. │ ├── mcp_docs_server.py # Layer 4 — document store server
  111. │ ├── mcp_case_server.py # Layer 4 — case management server (only writer)
  112. │ ├── mcp_common.py # shared SDK compat + token boundary
  113. │ ├── toolkit.py # shared svc_* functions (single source of truth)
  114. │ ├── api.py # FastAPI (claims, triage, ask, queue, usage, eval, runs, ml)
  115. │ ├── evaluate.py # Phase 6 evaluation harness
  116. │ ├── tracing.py # persisted run traces (data/runs.jsonl)
  117. │ ├── severity.py # severity regression + KMeans clusters + SHAP
  118. │ ├── ml_data.py # synthetic claims history (replace with real labels)
  119. │ ├── drift.py # PSI drift monitoring
  120. │ ├── fairness.py # segment parity audit
  121. │ ├── compliance.py # routing gate + borderline notes
  122. │ ├── ingest.py # document → text → agent extraction → claim JSON
  123. │ ├── prompts.py # prompt registry (version + content digest)
  124. │ └── usage.py # token/cost accounting (JSONL)
  125. ├── frontend/ # React + Vite console
  126. └── tests/ # 36 tests
  127. ```
  128. ## Design notes
  129. - **Deterministic triage.** Risk scores are weighted rules, never LLM judgment — identical
  130. inputs route identically, and every point is attributable to a named signal with an
  131. evidence span. The LLM orchestrates and explains.
  132. - **Refuse, don't guess.** Retrieval filters by claim type + region before ranking; empty
  133. retrieval returns `REFUSED` without calling the model.
  134. - **Hybrid retrieval.** BM25 + hosted embeddings fused with reciprocal rank fusion when an
  135. index exists (`cli reindex`); BM25 alone offline, so nothing breaks without a key.
  136. - **Guardrails.** Inputs and retrieved chunks are scanned for instruction hijacking; PII is
  137. redacted before prompts; answers' citations are verified against the retrieved set.
  138. - **Traces + cost.** Every run is persisted to `data/runs.jsonl` (tools, args, prompt
  139. versions, outcome); every model call is metered in `data/llm_usage.jsonl` and surfaced in
  140. the UI and `GET /api/usage`.
  141. - **Same tools, two transports.** Layer 4 is three least-privilege stdio servers —
  142. claims (read-only), documents, case-management (the only writer) — merged by one client;
  143. direct and MCP paths call the same `svc_*` functions, and a parity test asserts the union
  144. matches. Servers refuse to start without `MCP_AUTH_TOKEN`.
  145. - **Model layer.** Gradient-boosted severity regression (MAE ≈ $3.9k vs $12.9k baseline,
  146. R² 0.84 on synthetic history), KMeans anomaly clusters with severity profiles, and SHAP
  147. drivers per claim — surfaced as "expected cost" in the console via `/api/severity/{id}`.
  148. Labels are synthetic; the pipeline is the deliverable.
  149. - **Drift + fairness.** PSI monitoring per feature (`cli drift`, retrain verdict at >0.2) and
  150. a segment parity audit (`cli fairness`) that also proves protected attributes are excluded
  151. from model features.
  152. - **Compliance gate + human decisions.** Routing is blocked deterministically when a claim is
  153. closed/denied, already routed, below threshold, or a signal lacks evidence; scores within
  154. ±0.10 of the threshold carry a borderline note. Every routing record includes the model's
  155. expected cost and SHAP drivers. Adjusters record accept/override (with reason) and the
  156. override rate is surfaced in the UI and `GET /api/queue`.
  157. - **Evaluation gate.** The golden set must pass before shipping — `pytest` runs it offline,
  158. `cli eval --live` runs it against the model.
  159. - **Prompt provenance + cost.** Prompts live in `prompts/` with declared versions and
  160. content digests; every LLM call logs tokens and estimated cost to
  161. `data/llm_usage.jsonl` (surfaced in the UI and `GET /api/usage`).
  162. - **Human-in-the-loop.** The agent cannot approve or deny; it routes to an adjuster with
  163. score, reasons, and summary attached.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.