| title | Recoupe |
|---|---|
| emoji | 💸 |
| colorFrom | indigo |
| colorTo | blue |
| sdk | docker |
| app_port | 7860 |
| pinned | false |
| short_description | Autonomous AI subrogation recovery platform |
A swarm of AI agents that reads every closed insurance claim, figures out who was actually at fault, calculates what's recoverable, and autonomously pursues the money — including the long tail of small claims human adjusters never touch.
This repo is a working, runnable implementation of the Recoupe blueprint. It runs end-to-end for $0 with no API keys (deterministic offline mode) and lights up real free-tier LLMs (Gemini / Groq / Ollama via LiteLLM) when keys are present. The keystone — the Synthetic Claim Generator with ground truth — is built first, so every agent is graded against a labeled eval set.
Raw claim docs ─▶ Intake ─▶ Liability ─▶ Quantum ─▶ Strategy ─┬─▶ drop/monitor
(Bronze) (Silver) (RAG+rules) (Python math) (EV) │
└─▶ Demand ─▶ Negotiation ─┬─▶ Recovered
(human gate) (loop) └─▶ Litigation (arbitration)
every step → immutable audit trail + grounded citations (Guardrail layer)
python3 -m venv .venv && source .venv/bin/activate
pip install -e . # core (pydantic only) — offline demo works now
# optional power-ups:
pip install -e ".[api,llm,docs,dev]" # FastAPI + LiteLLM + PDF demands + pytest
# 1) Watch the full pipeline run on synthetic claims (with the Agent Trace):
python recoupe_cli.py demo --n 5 --trace
# 2) Grade the agents against ground truth (blueprint Part 12):
python recoupe_cli.py eval --n 80
# 3) Generate a batch, then run one claim and print its demand package:
python recoupe_cli.py generate --n 20
python recoupe_cli.py run --claim CLM-00001 --show-demand
# 4) Launch the API + console (needs the `api` extra):
uvicorn apps.api.main:app --reload # then open http://localhost:8000RECOUPE_OFFLINE=1 forces deterministic mode (used by CI/eval). Drop a
GEMINI_API_KEY / GROQ_API_KEY into .env (see .env.example) to enable
LLM narrative polish — the numbers and citations stay deterministic either way.
liability MAE 3.99 pts · 95% within ±10 pts
quantum mean error 9.1%
triage precision 1.00 · recall 0.92 · F1 0.96
recovery rate 55.8% of truly-recoverable dollars
citation integrity 100% (Guardrail-enforced — no unsourced legal claims)
autonomy rate 97.5%
| Blueprint layer | Where it lives |
|---|---|
| ClaimState backbone | agents/state.py, agents/schemas.py |
| Supervisor / Router | agents/supervisor.py |
| 7 agents | agents/intake.py · liability · quantum · strategy · demand · negotiation · litigation |
| Compliance Guardrail layer | agents/guardrails.py |
| Stateful graph (cyclic, human-gated) | agents/graph.py (built-in runner + optional LangGraph build) |
| Codified legal reasoning (regime + SoL per state) | knowledge/rules/negligence.py |
| Knowledge base + RAG | knowledge/kb.py, knowledge/ingest/build_kb.py |
| Carrier / Liability Graph | knowledge/carrier_graph.py |
| Model router (Gemini/Groq/Ollama via LiteLLM) | models/router.py |
| Synthetic Claim Generator (keystone) | data/generator/generator.py |
| Deterministic calculators ("Python does the math") | core/calculators.py |
| Medallion data lake (Bronze/Silver/Gold/outcomes) | data/lake.py |
| Public-source connectors (FARS/DE-SynPUF/NOAA shapes) | data/sources/ |
| Eval harness (accuracy vs. ground truth) | eval_harness/harness.py |
| API gateway (+ SSE live trace, analytics) | apps/api/main.py |
| Console (calm command-center UI) | apps/console/index.html |
| Deployment / infra | infra/ |
- Agents never depend on a live model. Each runs a deterministic, citation-grounded reasoning path; the LLM only polishes prose. This keeps eval reproducible and guardrails enforceable — and makes the $0 demo real.
- The LLM never does arithmetic. Quantum math is pure Python (core/calculators.py); the same formula computes ground truth and predictions from different fault inputs.
- No hallucinated law. Every citation an agent emits must trace to a retrieved KB chunk or a codified rule, or the Guardrail layer flags it and opens a human gate. Citation integrity is a measured metric.
- Audit-grade by construction. Every decision appends an immutable
AuditEntry(agent, model, confidence, evidence, guardrail flags, approver).
GET / console · GET /mode · POST /claims/generate?n=&run= ·
GET /claims · GET /claims/{id} · POST /claims/{id}/run ·
GET /claims/{id}/stream (SSE live Agent Trace) · GET /analytics ·
POST /eval?n=&seed= · OpenAPI at /docs.
Built here: Phase 0 (foundations, model router) · Phase 1 (Synthetic Claim Generator + ground truth) · Phase 2 (Intake + Liability + KB) · Phase 3 (Quantum + Strategy + pipeline KPIs) · Phase 4 (Demand + simulated Negotiation) · Phase 5 (Litigation + Analytics + outcome feedback loop + full eval harness).
Next: harden the document parser for real OCR/scans (Docling/Tesseract), swap the keyword RAG for Chroma/pgvector embeddings, replace the simulated carrier with the live counter-party channel, and build out the full Next.js console (the single-file console here is a faithful stand-in for Part 8).
pytest eval_harness/tests -q