Inspiration

Medical bills and EOBs are a black box—tables, modifiers, footnotes, and policy fine print that most people can’t decode. We wanted a copilot that doesn’t summarize your bill; it proves it. That “proof-first” mindset drove every decision: deterministic math, table-cell citations, policy simulation, and one-click, evidence-backed appeals. Constraints (no budget, 6 days) forced us to be ruthless, inventive, and laser-focused on UX clarity and technical verifiability.

What it does

LumiClaim is a proof-first medical billing copilot that turns opaque EOBs/bills into auditable answers and ready-to-send appeals. Explain with proof: Deterministic money math tied to page/table-cell citations and a colored Verifiability Score. Show my math: Human-readable formulas with inputs and sources (no hallucinated numbers). Policy Simulation (PSL): “What should I owe?” using deductible, coinsurance, and OOP max; show the delta vs. the bill. Hybrid++ Retrieval (Elastic): BM25 + kNN vectors fused with Reciprocal Rank Fusion and role bias toward tables for money questions; in-app retrieval debug. Evidence Graph: A compact graph of amounts, codes, and citations (supports/derived-from/contradicts). Delta Detective: Doc-to-doc diff with one-sentence root-cause (e.g., modifier rebundling). Appeal-as-Code: Persona-aware DOCX/PDF appeal packs with exhibits, charts, citations, and an audit hash. Uploads & Profiles: Users upload PDF/Word/Image EOBs; add plan details (deductible, coinsurance, OOP max); we persist per-session safely with 1-click purge. Dashboards: YTD OOP progress, stacked bars (billed/allowed/paid/adjustments/patient), top CPTs, and “what-if” sliders to project OOP max. Personas & Reading Levels: Patient/Payer/Provider voices at Grade 4/6/8/Pro; optional EN/ES/HI phrasing for core lines.

How we built it

Stack: Streamlit (UX), FastAPI (API), Docker Compose (local dev), GitHub Actions (CI). Elastic (Hybrid Search): Two indices: claims_raw: {session_id, doc_id, page, raw_text, page_anchor, raw_vector(384)} claims_struct: normalized rows with codes/amounts + raw_vector(384) Query: BM25 + kNN → RRF → role bias (tables > prose) → top-k with “why”. Kibana dashboard (.ndjson) for instant corpus viz. Google (Gemini/Vertex): Gemini 1.5 Flash verbalizes PME/PSL outputs (persona + reading level). Guardrail: LLM only sees our structured payload; it cannot invent numbers. Feature flags let the app run fully local (free) or partner-powered. Deterministic Core (PME/PSL): PME computes each field with sources and exposes calcs. Novel data model: Session-scoped storage, audit hash on outputs (SHA-256), PHI redaction at ingest, synthetic dataset generator for 20+ EOB variants. Exports: python-docx + pure-Python PDF to generate professional letters with exhibits and charts. Tests/CI: Unit tests for PME/PSL/copywriter/adapters; YAML lint; compose config validation; mocked adapter tests.

Challenges we ran into

Layout extraction: Tables vary wildly; we built normalizers and graceful fallbacks (manual entry if OCR is missing). No-hallucination constraint: Forbidding the LLM from “doing math” meant stricter contracts and more backend logic—but the trust payoff is huge. Hybrid ranking: Tuning RRF and role bias so table rows outrank prose without breaking semantic recall. Zero budget: Everything needed to run locally; we built adapters and feature flags to keep the demo crisp without paid infra. Clarity at speed: Many users are stressed—persona + reading level + glossary made the UX feel humane, not clinical.

Accomplishments that we're proud of

Proof-first, end-to-end: From upload → explain with table-cell citations → policy counterfactual → appeal pack with audit hash. Partner-grade retrieval: Elastic BM25+kNN+RRF with role bias and an explainable retrieval debug panel. Evidence Graph & Risk Flags: Judges can see the support graph and coding heuristics (dup charges, modifier anomalies). Exports that matter: DOCX/PDF letters that look like something a payer/provider would actually use. Trust UX: Verifiability Score ladder, warnings banner, audit trail, session purge.

What we learned

Proof beats prose. Users convert when they can verify line by line. Explainability sells. Retrieval debug + “show my math” built instant credibility. Persona matters. Patient vs. Payer vs. Provider tone changes comprehension dramatically. Hybrid > single-mode. Role-biased RRF reliably surfaces the right table cells. Packaging wins. A clean demo script + dashboards + exports make the innovation tangible.

What’s next for LumiClaim — Proof-First Medical Billing Copilot

Precision highlights: Bounding-box PDF viewer that jumps to the cited cell. Policy packs: Payer-specific rules, modifiers, and bundling policies with tests. Learning loop: Outcome-tracked appeals → rule tuning → improved PSL deltas. Integrations: EMR/RCM pipes; secure storage with org-level identity; HIPAA hardening. Multilingual depth: Full narratives in ES/HI beyond key phrases; locale-aware currency/formatting. Benchmarks: Public synthetic suite for retrieval/table accuracy and policy-variance detection.

Built With

• altair-(charts)
• audit-hashes-(sha-256)-**dashboards**-*-kibana-(saved-objects-.ndjson)
• camelot-py-/-tabula-py-(tables)
• cpts
• fallback-to-local-copywriter)-**data-&-parsing**-*-pandas
• feature-flags-(`use-elastic`
• fpdf2/reportlab-(pdf)-**devops-&-tooling**-*-docker-&-docker-compose
• github-actions-ci
• github-codespaces
• in-app-streamlit-dashboards-(ytd/oop
• json-**frontend**-*-streamlit-(ui)
• kibana-(dashboard)
• languages-&-core**-*-python-3.11
• markdown/latex-(docs)
• numpy
• optional)-plotly/pyvis-for-graph-viz-**backend**-*-fastapi
• optional)-pytesseract-(ocr-fallback)-**deterministic-engines**-*-pme-(provenance-math-engine)-?-custom-math-+-citations-*-psl-(policy-simulation-layer)-?-custom-benefits-logic-**exports**-*-python-docx-(docx)
• pdfplumber-(pdf-text)
• phi-redaction-(regex)
• pydantic
• python-docx-(word)
• python-dotenv-**retrieval-&-search**-*-elasticsearch-8.x-(bm25-+-knn-vectors)
• rank-bm25`
• requests
• rrf-fusion-(custom)-**ai/llm-(verbalization)**-*-google-gemini-1.5-flash-via-**ai-studio**-api-(free-tier)-or-vertex-ai-sdk-(feature-flagged
• sentence-transformers`-(embeddings)
• use-vertex`)-**security-&-privacy**-*-session-scoped-storage
• uvicorn