medical-bill-reconciliation

Medical Bill Reconciliation

Overview

Check provider bills against the insurer's Explanation of Benefits (EOB), track deductible and out-of-pocket totals, and produce a short exceptions list with draft inquiries a human sends.

The work is split into stages that never share access:

1. Collect. Per-portal collectors download PDFs into an inbox folder. Nothing else.
2. Extract. scripts/eob_extract.py dumps PDF text and tables; the agent maps them into fixed CSV rows, each keeping its source file and page.
3. Validate. scripts/reconcile.py validate checks columns, dates, money, and EOB arithmetic.
4. Reconcile. scripts/reconcile.py run matches bills to EOB lines and writes matches.csv, exceptions.csv, summary.json.
5. Review. The agent summarizes exceptions by dollar amount and drafts inquiries. A human decides and sends. Output columns and status values are listed in references/exception-codes.md.

The scripts are offline and give the same output for the same inputs and --as-of date. The reconciler is stdlib-only; the extractor needs pdfplumber.

Where data leaves the machine: the scripts never send anything, but the Mapping step puts PDF text in front of the model, and any report delivered through a messaging gateway carries patient labels, providers, claim numbers, and amounts. For local-only processing, use a local model and deliver reports to a local file or the terminal.

When to Use

• Matching medical statements to EOBs, finding overbilling, duplicate charges, or bills with no EOB.
• Turning a pile of EOB PDFs into a spreadsheet with traceable source pages.
• Tracking deductible and out-of-pocket progress from EOBs.
• Setting up a monthly unattended billing check.

Don't use for: filing appeals or calling insurers on someone's behalf, paying bills, interpreting coverage or medical necessity, or anything requiring the agent to log in to a main email inbox.

Quick Start

SKILL=~/.hermes/skills/productivity/medical-bill-reconciliation
mkdir -p ~/medical-billing/{inbox/eob,inbox/bills,processed,extracted,data,runs}
cp $SKILL/templates/eob_lines.csv $SKILL/templates/bill_lines.csv $SKILL/templates/providers.csv ~/medical-billing/data/
cd ~/medical-billing

python3 $SKILL/scripts/eob_extract.py inbox/eob/*.pdf inbox/bills/*.pdf --out extracted/
# agent maps extracted/*.json into data/eob_lines.csv and data/bill_lines.csv
python3 $SKILL/scripts/reconcile.py validate --eob data/eob_lines.csv --bills data/bill_lines.csv --aliases data/providers.csv
python3 $SKILL/scripts/reconcile.py run --eob data/eob_lines.csv --bills data/bill_lines.csv \
  --aliases data/providers.csv --deductible 3000 --oop-max 8000 \
  --as-of 2026-04-01 --out runs/2026-04-01