ProofNote

ProofNote is the adversarial trust layer for ambient clinical notes:

Abridge writes the note. ProofNote makes it safe to sign.

An Evidence Agent proposes clinical and billing candidates. A Skeptic Verifier Agent tries to disprove each one. Deterministic gates validate candidate provenance, code allowlists, policy dates, required billing context, duplicate services, and explicit diagnoses before a Grounded Revision Agent produces the final note.

Every candidate code becomes one of:

SUPPORTED, NEEDS_CLARIFICATION, CONTRADICTED, BLOCKED_BY_RULE, NOT_EVALUATED, or WITHHELD.

The memorable behavior is that one AI can overrule another—and the system can refuse to ship a code.

This repository uses only synthetic Abridge hackathon data. It is not for clinical care, coding decisions, or claim submission.

Run it

Requirements: Python 3.12 and uv.

uv sync
cp .env.example .env

Add ANTHROPIC_API_KEY to .env, load it into your shell, and start the application:

set -a
source .env
set +a
uv run uvicorn proofnote.main:app --reload

All agents use claude-sonnet-5. The model setting is exposed as ANTHROPIC_AGENT_MODEL but deliberately rejects other model IDs for this MVP. Configure reasoning with ANTHROPIC_REASONING_EFFORT; accepted values are low, medium, high, xhigh, and max.

Three-minute demo

1. Set up the problem: select the hypertension encounter and briefly explain the risks a single coding pass can miss: obesity inferred from BMI, duplicate depression-screening FHIR, and guessed office billing context.
2. Run the workflow: click Run end-to-end agent review. The scoreboard appears, and each candidate shows the Evidence Agent proposal beside the Verifier override and deterministic gate. Click an evidence chip to jump to the exact transcript line or FHIR pointer.
3. Resolve and finish: answer every clinician question locally, then submit the complete set once. A single verifier call processes the batch, the scoreboard updates, answers become clinician provenance, and finalization produces a note diff and downloadable manifest.

The application always runs the live Sonnet 5 agent workflow. Record the submission and backup video after validating the complete live flow; no cached agent output or pre-authored case result is bundled.

Dataset coverage

All 25 synthetic encounters can be selected and analyzed. Every case receives:

• Transcript, note, and FHIR provenance
• Derived insurance and encounter context when available
• Deterministic FHIR reconciliation findings
• Draft-assessment and structured-condition facts
• Sonnet 5 Evidence and Coding Agent proposals
• Sonnet 5 Policy and Verification Agent critique
• Sonnet 5 Grounded Note Revision Agent at finalization
• An explicit final-review and manifest-export step

All 25 encounters use the same live Evidence, Verifier, deterministic-gate, clarification, and Revision pipeline. The local code and policy catalogs remain deliberately narrow, so terminology without a reviewed mapping stays NOT_EVALUATED rather than being presented as billing advice.

Architecture

Abridge JSONL
  ├─ transcript + ambient note ──> stable line sources
  ├─ encounter FHIR ─────────────> normalized resources + JSON pointers
  └─ PRAPARE insurance ──────────> broad derived payer category
                    │
                    v
       Evidence and Coding Agent
                    │ assertive proposals
                    v
         Skeptic Verifier Agent
                    │ agrees / downgrades / blocks
                    v
    deterministic validation boundary
                    │
          physician clarification
                    │ verifier rerun
                    v
        Grounded Note Revision Agent
                    │
                    v
          finalized evidence manifest

The FastAPI service keeps analysis runs in memory and never writes transcripts or notes to application storage or logs. The frontend is plain HTML, CSS, and JavaScript—there is no frontend build step.

Key files:

• proofnote/data.py — Abridge loader, provenance normalization, payer extraction, deterministic anomaly checks
• proofnote/analyzer.py — grounded base analysis, physician-confirmation handling, and finalization state
• proofnote/claude.py — three Sonnet 5 agents, structured schemas, deterministic validation gates, and CMS-domain search
• config/code_catalog.json — deliberately small code allowlist
• config/policy_pack.json — dated executable rule citations and declarative gates
• config/clarification_catalog.json — clinician questions, answer choices, and resolution effects for missing context and FHIR ambiguity
• proofnote/main.py — API and in-memory run store
• proofnote/static/ — focused review interface

API

• GET /api/encounters
• GET /api/encounters/{id}
• POST /api/analyses
• POST /api/analyses/{run_id}/clarifications
• POST /api/analyses/{run_id}/finalize
• GET /api/analyses/{run_id}
• GET /api/analyses/{run_id}/manifest
• Interactive OpenAPI documentation: /api/docs

List the available synthetic encounters:

curl -s http://127.0.0.1:8000/api/encounters

The browser supplies the selected encounter ID and confirmed context. Every analysis invokes the live agent workflow. Set include_live_search to true only when supplemental CMS research is wanted.

Tests

uv run pytest

The test suite covers all 25 encounters, all four insurance codes, missing insurance, FHIR provenance counts, separate proposer/verifier decisions, scoreboard updates, actionable duplicate reconciliation, conflicting medication state, context-dependent NOT_EVALUATED rules, allowlist/source rejection, clarification isolation and outcomes, revision provenance, finalization gates, mandatory live-agent configuration, and a mocked live-agent API flow.

Safety boundaries

• The bundled data is synthetic and the generated output has not been clinically reviewed.
• PRAPARE Primary insurance is only a broad category. It is not eligibility, a member record, a FHIR Coverage resource, or an exact plan.
• Exact payer rules, Medicaid delivery model, service jurisdiction, place of service, authorization, network, benefits, medical necessity, claim history, and commercial-payer policy are not inferred.
• Sonnet 5 can infer facts and code proposals, but cannot add a code outside the local allowlist or cite a source ID that does not exist.
• Candidate relationships, required billing context, duplicate resolution, and explicit-documentation requirements are configuration-driven; Python contains no encounter- or code-specific clarification branches.
• Live search is restricted to cms.gov and api.coverage.cms.gov, labeled UNREVIEWED_SUPPLEMENTAL, and cannot alter curated verdicts.
• A measurement does not replace an explicit provider diagnosis when the reviewed rule requires one.
• The app does not sign notes, submit claims, estimate payment, or promise that a claim will not be denied.

Reviewed public sources

• FY 2026 ICD-10-CM Official Guidelines
• CMS National Correct Coding Initiative
• CMS Evaluation & Management compliance guidance
• CMS Coverage API
• Anthropic structured outputs
• Anthropic extended thinking
• Anthropic server tools and domain filtering
• Anthropic model overview

The curated pack is intentionally narrow and must be reviewed by a qualified coding specialist before any real-world use.