🔁 ReconcileAI

An AI-assurance month-end close reconciliation engine — the LLM explains, the code decides, the human approves.

ReconcileAI reconciles GL entries against bank statements, classifies every transaction with a deterministic matching engine, applies materiality and risk governance, routes exceptions to a human, and records every decision in an immutable, hash-chained audit log. The AI only writes plain-English explanations for exceptions — no LLM call ever approves, rejects, or modifies a record.

🧪 Synthetic Data Demo — a portfolio project by Jay A. Patel. Not production software; not tested against real financial systems.

_{More views: reconciliation table · exception queue}

---

The problem

Month-end close takes 6–10 business days (target: <4); 59% of finance teams still reconcile in spreadsheets; reconciliation exceptions eat 30–40% of close time, and mismatches cascade into restatements, audit findings, and SOX issues. BlackLine and Trintech built billion-dollar businesses here. ReconcileAI is a live proof-of-concept of the same architecture at portfolio scale.

Architecture — 3-agent pipeline

   Synthetic GL + bank + sub-ledger (messy: date formats, truncated names, fees)
                                   │
                                   ▼
        ┌───────────────────────────────────────────────┐
        │  AGENT 1 — EXTRACTOR                            │
        │  normalize dates, amounts (cents), descriptions │
        └───────────────────────┬───────────────────────┘
                                 ▼
        ┌───────────────────────────────────────────────┐
        │  AGENT 2 — AUDITOR   (deterministic, no LLM)   │
        │  exact · fuzzy · duplicate/missing detection    │
        │  → MATCHED · PARTIAL_MATCH · UNMATCHED · ANOMALY│
        └───────────────────────┬───────────────────────┘
                                 ▼
        ┌───────────────────────────────────────────────┐
        │  AGENT 3 — GOVERNOR  (deterministic, no LLM)   │
        │  materiality auto-clear · risk score · escalate │
        │  immutable hash-chained audit log · human queue │
        └───────────────────────┬───────────────────────┘
                                 ▼
        ┌───────────────────────────────────────────────┐
        │  LLM EXPLANATION LAYER  (explanations ONLY)     │
        │  "why didn't this match?" + confidence          │
        │  never decides — graceful fallback without a key│
        └───────────────────────┬───────────────────────┘
                                 ▼
              Streamlit dashboard · human approves exceptions

The order is non-negotiable: the LLM explains → the code decides → the human approves.

Measured results (from actual runs against the hidden ground truth)

Scenario	GL / Bank	Match rate	Escalated	Review	Auto-cleared
Clean Month	500 / 495	97.5%	5	0	10
Messy Month	500 / 480	88.8%	20	8	37
Fraud Scenario	495 / 485	95.9%	10	6	9

Every seeded error (6 types: duplicate payment, timing, FX rounding, missing entry, amount mismatch, description mismatch) is caught and correctly classified; duplicates and missing entries always escalate; the audit-log hash chain validates end-to-end. 60 automated tests, one gate per milestone.

Quickstart

pip install -r requirements.txt
streamlit run app.py        # first launch builds the DB and processes all 3 scenarios

No API key required — offline, exception explanations show a graceful fallback while the deterministic rule reason carries the substance. To enable live LLM explanations, copy .env.example to .env and set ANTHROPIC_API_KEY (never committed).

Run the tests: pytest -q

Deploy to Streamlit Community Cloud

1. Push this repo to github.com/jpatel-strategy/reconcileai.
2. share.streamlit.io → New app → repo jpatel-strategy/reconcileai, branch main, main file app.py.
3. (Optional) add ANTHROPIC_API_KEY under Advanced → Secrets for live explanations. Deploy — first load builds the database automatically.

The pysqlite3-binary shim + st.cache_resource DB init are already wired, so the two Streamlit Cloud gotchas (old system SQLite, rerun races) are pre-empted.

Honest limitations

This is a portfolio demonstration using synthetic data. It is not production software and has not been tested against real financial systems. Single currency, single close period. 1:many/batch-split matching is scaffolded but not exercised (no split transactions are seeded — frozen v1 scope). "Hours saved" rests on an explicit, labeled touch-time assumption. Live-LLM token cost is not metered.

Project structure

src/reconcileai/
  config.py            tolerances, materiality, brand — one visible place
  money.py, taxonomy.py
  data/                deterministic generator + 3 scenarios + schema
  matching/            the Auditor (deterministic matching engine)
  governance/          the Governor (materiality, risk, escalation)
  db/                  SQLite schema, hash-chained audit log, exception queue
  agents/              LLM explanation layer (explanations only)
  llm.py, service.py   client wrapper + orchestration/bootstrap
tests/                 the per-milestone verification gates
app.py                 Streamlit dashboard (4 tabs)

ReconcileAI is part of a portfolio suite with AuditLedger.