Settlement-to-Cash Close Agent · Razorpay Buildathon Track 04 — AI Finance Controller
A settlement finance-ops agent that reconciles merchant activity, processor settlements, and bank cash across a full synthetic batch; reports measured match coverage; investigates only genuine ambiguity with AI; and leaves an explicit exception queue when the books cannot safely close.
Authority invariant: confidence never grants financial authority. AI can investigate and propose; it cannot post a match or certify a close.
The reviewer batch contains 177 immutable source facts: 59 merchant records, 59 processor records, and 59 bank records. The first close run projects 59 settlements and produces a measured result rather than a cherry-picked example:
| Metric | Result |
|---|---|
| Source facts | 177 |
| Projected settlements | 59 |
| Financially matched | 50 / 59 |
| Initial match rate | 84.75% |
| Open exceptions | 10 |
| AI-eligible cases | 3 (E09/E11 only) |
The unresolved queue is intentional: 3 delayed-bank cases (E06), 2 amount mismatches (E07), 2 unique inferred candidates requiring human approval (E08), 2 ambiguous matches (E09), and 1 unexplained processor-like credit (E11).
merchant truth ─────┐
processor truth ────┼─> source controls -> settlement projection
bank cash truth ────┘ |
v
deterministic reconciliation
| |
proven cash exceptions
|
bounded AI (E09/E11)
|
human review
|
deterministic Close Gate
The controller uses deterministic evidence precedence wherever proof exists. AI is reserved for ambiguity, executes outside the financial transaction boundary, and returns structured proposals that are revalidated before any human-authorized financial commit.
The reviewer can ask questions such as:
- Why is the close blocked?
- What is the match rate and what remains unresolved?
- Which exceptions carry the most cash exposure?
- Which settlements are still waiting for bank cash?
- Summarize this close for the finance lead.
The model first selects from a bounded set of read-only finance tools (batch_metrics, close_summary, settlements, exceptions, cash_outlook, audit_recent). The server executes those tools against current financial state, then the model synthesizes an answer only from returned evidence. The UI exposes the tool trace.
Prerequisites: Docker Desktop, Python 3.11+, and Node.js/npm.
1. verify.bat
2. configure_ai.bat # optional; enables live Groq investigation + Q&A
3. run_app.bat
4. open http://127.0.0.1:8000/
verify.bat creates a fresh PostgreSQL database, installs project dependencies against backend/constraints.txt, builds the frontend, applies migrations, runs the full test/evaluation gates, and then loads the 177-fact reviewer batch in a pre-run state.
make setup
make verify
make appFor the full containerized reviewer stack (database, migrations, seed data, and app):
docker compose -f docker-compose.app.yml up --buildThe repository includes a fixed-seed evaluation harness and a separate adversarial holdout:
- 84 scenarios / 234 financial source facts
- 36/36 deterministic scenarios
- 24 E09 ambiguity cases
- 24 E11 unexplained-credit cases
- 0 incorrect financial auto-resolutions
- 0 bank-entry reuse violations
- 0 certified closes with material unexplained cash
- F01/F02 recovery: 2/2
- independent adversarial holdout: 9/9
The deterministic E09/E11 CI baseline is not presented as live-model accuracy.
.
├── backend/
│ ├── app/ # runtime modules and financial control loop
│ ├── alembic/ # PostgreSQL schema + invariant migrations
│ ├── constraints.txt # pinned Python dependency baseline
│ ├── evals/ # isolated ground truth and evaluation harness
│ ├── scripts/ # local AI / reviewer setup helpers
│ └── tests/ # unit, integration, concurrency and invariant tests
├── frontend/ # React + TypeScript reviewer UI
├── fixtures/reviewer_batch/ # 177-fact reviewer batch only
├── docs/
│ ├── adr/ # architecture decision records
│ ├── ARCHITECTURE.md
│ ├── DOMAIN_MODEL.md
│ ├── MATCHING_POLICY.md
│ ├── FAILURE_MODES.md
│ ├── EVALUATION.md
│ ├── SECURITY.md
│ ├── LIVE_AI.md
│ └── REVIEWER_GUIDE.md
├── .github/workflows/ci.yml
├── Dockerfile
└── docker-compose*.yml
Test-only fixture sets live under backend/tests/fixtures/; runtime code never depends on them.
This is intentionally a modular monolith. PostgreSQL is the financial authority. The design avoids queues, vector databases, workflow engines, and microservice boundaries that do not improve this close loop.
Key controls:
- source facts are append-only;
- merchant ↔ processor truth gaps block close (E04/E05);
- one bank entry cannot be consumed by two settlements;
- inferred matches require human approval;
- proposal/source fingerprints are revalidated before commit;
- close certification is deterministic and input-watermark aware;
- certified history is immutable; later contradictions become
POST_CLOSE_EXCEPTION; - reviewer HTTP mode is loopback-only by default.
See docs/ARCHITECTURE.md, docs/MATCHING_POLICY.md, and the docs/adr/ records for the reasoning behind these choices.
The supported reviewer provider is Groq using openai/gpt-oss-20b with strict JSON Schema output and low reasoning effort. Configure it with configure_ai.bat; the key is written only to local .env, which is gitignored.
The deterministic close, tests, evaluation harness, and UI remain usable without an AI key.
This is a Buildathon implementation, not a production-readiness claim. A production deployment would additionally require authenticated identity/RBAC, tenant isolation, managed secrets, TLS, observability, retention/PII controls, rate limiting, and formal security/compliance review.