Raze reconciliation backlogs. Resolve financial discrepancies. Prove every decision.
RAZE is an agentic financial reconciliation and control system designed to reconcile heterogeneous payment and settlement records, investigate discrepancies, quantify uncertainty, and determine when a financial operation can be safely automated or requires human intervention.
Built for the Razorpay AI Finance Controller track using Razorpay Test Mode and controlled synthetic financial data.
- How to Run
- Why RAZE
- Core Principle
- The Problem
- What RAZE Does
- Architecture
- Reconciliation Pipeline
- Deterministic Financial Verification
- Multi-Record Reconciliation
- Agentic Investigation
- Evidence & Explainability
- Confidence-Aware Automation
- Human-in-the-Loop Learning
- Risk-Sensitive Policy Learning
- Product Experience
- Benchmark & Evaluation
- System Reliability
- Technology Stack
- Repository Structure
- Security & Financial Controls
- Deployment
- Roadmap
RAZE runs as three local pieces: a PostgreSQL container, the Go control plane (:8080), and an optional Python AI service (:8090). Two launcher scripts below manage the whole stack — including first-time setup — so a typical first run is a single command.
| Tool | Needed for | Notes |
|---|---|---|
| Docker (compose) | PostgreSQL | docker compose, or podman with the compose plugin |
| Go ≥ 1.23 | control plane + TUI | stdlib-only; no external Go dependencies |
| Python ≥ 3.14 | AI service (optional) | venv + deps auto-created on first run (needs network) |
make |
convenience | wraps the launchers |
No .env is required to run. Without one RAZE uses local defaults, the deterministic heuristic-v1 investigator, and synthetic settlement data. Copy .env.example to .env only to opt into the optional Gemini / Razorpay features below.
make tui # or: bash scripts/tui.shscripts/tui.sh does everything in order:
- starts PostgreSQL (
docker compose up -d postgres) and waits for it to be ready; - applies migrations (
go run ./cmd/migrate); - generates the synthetic benchmark when it is missing — 150 settlements, 30 % corruption, seed 42 — writing
data/benchmark/records.json+ground_truth.json; - starts the Python AI service in an auto-created
ai/.venv(degrades gracefully to deterministic-only when Python, dependencies or network are unavailable); - builds and starts the Go API on
http://localhost:8080; - when the control plane is empty, imports the records and runs a first reconciliation automatically;
- launches the interactive raze-tui.
Inside the TUI: select a job, open its items, then open an item to inspect the record, its matched record, candidates, evidence, audit trail and the AI investigation (the model=… label shows which investigator advised it). The active keys are always shown in the footer; q quits and stops the services the script started.
bash scripts/demo.shThe same bootstrap without the TUI: prints each step, imports records, runs a reconciliation job, waits for completion, then prints the final job JSON — including its matched / review / escalated counts — and the review-endpoint hints. This is the path to capture for a terminal recording.
docker compose up -d postgres # 1. PostgreSQL
make migrate # 2. apply migrations
python3 data/generator/generate.py --n-settlements 150 --corruption-rate 0.30 --seed 42 # 3. benchmark data
make api-run # 4. Go control plane -> http://localhost:8080
make ai-run # 5. Python AI service -> http://localhost:8090 (optional)
make test # 6. go test ./...Useful API endpoints once the API is up: GET /healthz, POST /api/v1/records/import, POST /api/v1/records/sync/razorpay, GET /api/v1/jobs, GET /api/v1/jobs/{id}, GET /api/v1/jobs/{id}/items, GET /api/v1/items/{id} (record + match + candidates + evidence + audit + AI advice), and POST /api/v1/items/{id}/review.
Set in .env (or your shell) to add an LLM-backed second opinion on every REVIEW / ESCALATE case:
| Variable | Default | Behaviour |
|---|---|---|
GEMINI_API_KEY |
(unset) | absent → deterministic investigator only |
GEMINI_MODEL |
gemini-3.6-flash |
model id (Google retired gemini-2.5-flash for new keys) |
RAZE_AI_BACKEND |
auto |
auto = Gemini, silent fallback to heuristic on any error; gemini = required (fails closed); heuristic = always deterministic |
Set RAZORPAY_KEY_ID / RAZORPAY_KEY_SECRET with test-mode keys only and keep RAZORPAY_MODE=test. When credentials are absent, RAZE runs entirely on synthetic settlement data.
The launchers reuse existing data once the control plane is non-empty, so a genuinely fresh run needs both:
docker compose down -v # drop the dev Postgres volume
rm -f data/benchmark/records.json data/benchmark/ground_truth.json # force data regeneration
make tui # or: bash scripts/tui.shFinancial operations rarely exist in one clean database.
A real reconciliation workflow may involve:
- Payments
- Orders
- Settlements
- Processing fees
- Taxes
- Refunds
- Chargebacks
- Merchant ledgers
- Batched settlements
- Partial settlements
- Multiple currencies
- Missing or duplicated records
Traditional rule-based reconciliation works well when records are clean and relationships are obvious.
The problem begins when reality is ambiguous.
Payment A ──────┐
Payment B ──────┼────── Settlement Batch
Payment C ──────┘
↓
Is this relationship correct?
Are the fees explained?
Are taxes correct?
Is there a missing record?
Should this be automatically reconciled?
Or should a human intervene?
RAZE treats this as a controlled decision system, not simply a matching problem.
Trustworthy autonomy over maximum automation.
RAZE separates authoritative financial logic from probabilistic intelligence.
Financial Data
│
▼
Deterministic Validation
│
▼
Candidate Generation
│
▼
Evidence Retrieval
│
▼
Agentic Investigation
│
▼
Confidence Estimation
│
▼
Risk Policy
│
┌────────────┼────────────┐
▼ ▼ ▼
MATCH REVIEW ESCALATE
│ │ │
└────────────┼────────────┘
│
▼
Human Feedback
│
▼
Learning & Calibration
│
▼
Audit Trail
The fundamental rule is:
Deterministic systems establish financial correctness. AI investigates ambiguity. Humans retain control over uncertainty.
Financial reconciliation is fundamentally a verification problem.
RAZE handles situations including:
| Problem | Example |
|---|---|
| Missing records | Payment exists but settlement is missing |
| Duplicate records | Same transaction appears multiple times |
| Amount mismatch | ₹10,000 payment → ₹9,800 settlement |
| Partial settlement | One payment settles across multiple records |
| Batched settlement | Multiple payments map to one settlement |
| Reference corruption | IDs differ slightly across systems |
| Refund | Reconciled payment is partially refunded |
| Chargeback | Transaction is adjusted after settlement |
| FX differences | Authorization in USD, settlement in INR |
| Fee mismatch | Unexpected processing fee |
| Tax mismatch | Incorrect tax calculation |
The challenge is not simply:
"Find the closest transaction."
It is:
"Can we prove that these financial records represent
the same underlying financial event?"
RAZE combines multiple layers of intelligence.
RAW RECORDS
│
▼
Normalization
│
▼
Deterministic Validation
│
▼
Candidate Generation
│ │ │
▼ ▼ ▼
Exact Fuzzy Semantic
│ │ │
└───────┼───────┘
▼
Candidate Ranking
│
▼
Evidence Construction
│
▼
Agent Investigation
│
▼
Confidence Estimation
│
▼
Risk Policy
│
┌──────────────┼──────────────┐
▼ ▼ ▼
MATCH REVIEW ESCALATE
RAZE uses a deliberately separated architecture.
┌──────────────────────────────────────────────┐
│ │
│ RAZE Operations Interface │
│ │
│ Import → Reconcile → Investigate → Review │
│ │
└──────────────────────┬───────────────────────┘
│
REST / WebSocket
│
▼
┌──────────────────────────────────────────────┐
│ │
│ Go Control Plane │
│ │
│ • API │
│ • Workflow State │
│ • Financial Mutations │
│ • Authorization │
│ • Audit │
│ • Idempotency │
│ • Concurrency Control │
│ • Circuit Breaker │
│ │
└───────────────┬──────────────────┬───────────┘
│ │
gRPC PostgreSQL
│ │
▼ ▼
┌──────────────────────────┐ ┌───────────────┐
│ Python AI/ML Layer │ │ pgvector │
│ │ └───────────────┘
│ • Matching │
│ • Retrieval │
│ • Agents │
│ • Evidence │
│ • Confidence │
│ • Policy Learning │
│ • Evaluation │
│ │
└──────────────┬───────────┘
│
▼
┌──────────────────────────────────────────────┐
│ Financial Data Sources │
│ │
│ Razorpay Test Mode + Synthetic Benchmark │
│ + Human Feedback │
└──────────────────────────────────────────────┘
Go owns the authoritative financial state.
Responsibilities:
- HTTP API
- Request validation
- Workflow orchestration
- Database transactions
- State transitions
- Authorization
- Financial mutations
- Audit logging
- Idempotency
- Concurrency control
- Async job submission
- Circuit breaking
- WebSocket events
The control plane decides whether an action is legally allowed within the system.
Python owns probabilistic and research components.
Responsibilities:
- Candidate generation
- Fuzzy matching
- Semantic retrieval
- Agentic investigation
- Evidence construction
- Confidence estimation
- Policy inference
- Offline policy training
- Benchmark generation
- Evaluation
- Calibration
Python can recommend.
Python cannot directly mutate
authoritative financial state.
All state-changing operations must pass through the Go control plane.
Different sources use different schemas.
Payment Provider
{
payment_id,
amount,
currency,
created_at
}
Settlement System
{
settlement_id,
net_amount,
settlement_date
}
RAZE normalizes these records into a canonical financial representation.
Financial calculations are performed deterministically.
Example:
Payment ₹10,000
Processing Fee ₹150
Tax ₹27
────────────────────────────────
Expected Settlement ₹9,823
Actual Settlement ₹9,823
────────────────────────────────
Difference ₹0
Result:
RECONCILED
An LLM is never allowed to override arithmetic inconsistencies.
RAZE generates possible relationships using multiple strategies.
Financial Record
│
┌─────────────┼─────────────┐
▼ ▼ ▼
Exact Fuzzy Semantic
│ │ │
└─────────────┼─────────────┘
▼
Candidates
Signals may include:
- Exact transaction references
- Amount similarity
- Timestamp proximity
- Merchant similarity
- Currency compatibility
- Settlement structure
- Historical patterns
Candidates are not trusted merely because they look similar.
RAZE verifies:
Reference Match?
│
Amount Explained?
│
Fees Explained?
│
Taxes Explained?
│
Settlement Structure Valid?
│
Currency Conversion Valid?
│
Missing Evidence?
The result becomes structured evidence.
RAZE does not assume financial records have a simple 1:1 relationship.
Supported relationships:
1 Payment → 1 Settlement
N Payments → 1 Settlement
1 Payment → N Settlement Components
N Payments → N Settlement Components
Example:
PAY_001 ₹5,000
PAY_002 ₹8,000
PAY_003 ₹7,000
│
▼
Settlement Batch
│
Gross ₹20,000
Fee ₹400
Tax ₹72
│
▼
Net ₹19,528
The engine determines whether the settlement can be fully explained by the underlying financial records.
RAZE explicitly models difficult financial scenarios.
Expected: ₹10,000
Actual: ₹9,800
Payment exists
Settlement missing
PAY_1001
PAY_1001
Payment ₹20,000
Settlement A ₹12,000
Settlement B ₹8,000
Original Payment
↓
Reconciled
↓
Partial Refund
↓
Adjustment Event
Authorization
USD 100
FX Rate
₹83.20
Expected
₹8,320
Actual Settlement
₹8,295
Difference
₹25
RAZE distinguishes between:
- Expected FX variation
- Settlement timing differences
- Genuine reconciliation errors
RAZE uses specialized bounded agents.
It does not use an unrestricted autonomous agent.
Controller
│
┌─────────────┼─────────────┐
▼ ▼ ▼
Matcher Verifier Investigator
│ │ │
└─────────────┼─────────────┘
▼
Decision Policy
│
┌──────────┴──────────┐
▼ ▼
Resolve Escalate
Finds plausible candidate records.
Checks:
- Numerical consistency
- Structural consistency
- Financial relationships
- Deterministic rules
Explores unresolved ambiguity using available evidence.
Coordinates the investigation and enforces bounded execution.
RAZE does not rely on free-form explanations as the source of truth.
Every investigation produces a structured decision object.
{
"reconciliation_id": "REC_9021",
"decision": "RECOMMEND_MATCH",
"confidence_score": 0.92,
"evidence_chain": [
{
"type": "EXACT_REFERENCE_MATCH",
"source": "PAY_10023",
"target": "SETTLE_8801",
"weight": 0.4
},
{
"type": "FEE_BREAKDOWN_EXPLAINED",
"breakdown": {
"base": 12000,
"fee": 200,
"tax": 36
},
"unexplained_delta": 0,
"weight": 0.5
}
],
"abstention_reasons": []
}This allows the frontend and audit system to render evidence directly.
Evidence relationships are represented as a graph.
PAY_10023
│
│ EXACT_REFERENCE_MATCH
▼
SETTLE_8801
│
├──── FEE_RECORD
│ │
│ ▼
│ ₹200
│
└──── TAX_RECORD
│
▼
₹36
↓
FINANCIAL MATCH
Operators can inspect:
- Which records contributed
- Which relationships were exact
- Which relationships were inferred
- Which calculations were deterministic
- Which evidence was missing
- Why automation was rejected
RAZE treats confidence as a decision signal, not a guarantee.
Initial policy:
Confidence > 95%
│
▼
AUTO-RECONCILE
75% – 95%
│
▼
HUMAN REVIEW
< 75%
│
▼
ESCALATE
Confidence must be calibrated.
For example:
Predicted Confidence: 92%
Observed Accuracy: 78%
This indicates overconfidence.
RAZE continuously evaluates calibration against held-out ground truth.
Human review is not a dead end.
Every operator action becomes structured feedback.
Examples:
ACCEPTED_AGENT_MATCH
OVERRIDDEN_AGENT_MATCH
MANUALLY_LINKED_RECORDS
CONFIRMED_EXCEPTION
REJECTED_CANDIDATE
Feedback pipeline:
Agent Recommendation
│
▼
Human Decision
│
▼
Feedback Event
│
├──────────────► Confidence Calibration
│
└──────────────► Policy Training Dataset
Human decisions are stored as learning signals.
They do not immediately modify production behavior.
Human Feedback
│
▼
Experience Store
│
▼
Data Validation
│
▼
Offline Training
│
▼
Validation
│
▼
Held-Out Evaluation
│
▼
Policy Version
│
▼
Controlled Deployment
This prevents noisy feedback or a single incorrect decision from immediately changing autonomous financial behavior.
The policy controls intervention decisions, not financial truth.
Example signals:
amount_difference
amount_difference_ratio
date_difference
reference_similarity
merchant_similarity
fee_match
tax_match
historical_match_rate
candidate_count
confidence
transaction_value
exception_type
currency
settlement_type
refund_status
chargeback_status
AUTO_RECONCILE
REQUEST_REVIEW
INVESTIGATE
ESCALATE
Correct Auto-Reconciliation +10
Correct Review +3
Correct Investigation +3
Correct Escalation +5
Incorrect Auto-Reconciliation -50
Unnecessary Review -2
Unnecessary Investigation -1
Unnecessary Escalation -3
The heavy penalty for incorrect autonomous reconciliation reflects asymmetric financial risk.
RAZE evaluates whether complex learning is actually necessary.
Static Threshold
│
▼
Supervised Policy
│
▼
Contextual Bandit
│
▼
Adaptive RL Policy
The objective is not to claim that RL is automatically superior.
The objective is to measure whether adaptive policies improve the automation-risk trade-off.
RAZE is intentionally designed as a workflow-first financial operations application.
The product is not centered around:
- KPI cards
- Generic charts
- Analytics dashboards
- Decorative metrics
Instead, the interface follows the actual reconciliation workflow.
Import Records
│
▼
Run Reconciliation
│
▼
Review Results
│
▼
Investigate Exceptions
│
▼
Inspect Evidence
│
▼
Approve / Reject / Escalate
│
▼
Audit Record
The entry point for reconciliation.
Operators can:
- Import financial records
- Select reconciliation sources
- Start a reconciliation run
- Track processing state
- View completed runs
Example:
RECONCILIATION JOB #REC-1042
Status: INVESTIGATING
Records: 12,481
Matched: 11,902
Review Required: 421
Escalated: 158
Displays the actual output of a reconciliation run.
┌──────────────────────────────────────────────┐
│ PAYMENT SETTLEMENT STATUS │
├──────────────────────────────────────────────┤
│ PAY_1023 SET_8821 MATCHED │
│ PAY_1024 SET_8822 REVIEW │
│ PAY_1025 — ESCALATED │
└──────────────────────────────────────────────┘
Operators can drill directly into individual cases.
This is the core product experience.
┌─────────────────────────────────────────────┐
│ REC_9021 │
│ │
│ Status: REVIEW REQUIRED │
│ Confidence: 92% │
│ │
├─────────────────────────────────────────────┤
│ │
│ Candidate Records │
│ │
│ PAY_10023 Similarity: 98% │
│ PAY_10027 Similarity: 74% │
│ │
├─────────────────────────────────────────────┤
│ │
│ Evidence │
│ │
│ ✓ Exact reference match │
│ ✓ Amount explained │
│ ✓ Fee breakdown verified │
│ ✓ Tax calculation verified │
│ │
├─────────────────────────────────────────────┤
│ │
│ Recommendation │
│ │
│ REQUEST_REVIEW │
│ │
│ [Approve] [Reject] [Investigate] [Escalate] │
└─────────────────────────────────────────────┘
The operator sees the actual evidence behind the recommendation.
Operators can:
- Accept recommendation
- Reject recommendation
- Manually link records
- Request additional investigation
- Escalate exceptions
Every action generates a structured feedback event.
Each reconciliation has a complete history.
REC_9021
10:02 CREATED
10:03 MATCHING
10:03 CANDIDATES GENERATED
10:04 EVIDENCE VERIFIED
10:05 AGENT INVESTIGATION
10:06 REQUEST_REVIEW
10:10 HUMAN ACCEPTED
10:10 RESOLVED
The audit record stores:
- Decision
- Evidence
- Agent version
- Model version
- Policy version
- Previous state
- New state
- Human actions
- Timestamp
RAZE uses controlled synthetic financial data with known ground truth.
Example benchmark:
10,000 Financial Records
8,000 Normal
2,000 Corrupted
Corruption classes:
Amount mismatch
Missing settlement
Duplicate transaction
Date shift
Reference corruption
Partial settlement
Batched settlement
Refund
Chargeback
FX discrepancy
Fee discrepancy
Tax discrepancy
1-to-N mapping
N-to-1 mapping
- Precision
- Recall
- F1
- Match accuracy
- False Auto-Match Rate
- Incorrect Autonomous Action Rate
- High-value error rate
- Automation Rate
- Human Review Rate
- Exception Resolution Rate
- Throughput
- Latency
- Cost per record
- Confidence calibration
- Abstention quality
- Evidence coverage
- Agent failure rate
The deterministic engine and AI pipeline are benchmarked independently.
Measure:
Records / second
Requests / second
p50 latency
p95 latency
p99 latency
CPU utilization
Memory utilization
Measure:
Investigations / second
Average latency
p95 latency
LLM calls / investigation
Inference cost
Failure rate
RAZE publishes measured results rather than arbitrary performance claims.
Agent investigations may take longer than deterministic checks.
Therefore, long-running workflows are asynchronous.
Transaction
│
▼
Go Control Plane
│
▼
Redis / Asynq
│
▼
Python Worker
│
├── Retrieve Evidence
├── Match Candidates
├── Verify
├── Investigate
└── Generate Decision
│
▼
Go Control Plane
│
▼
PostgreSQL
│
▼
WebSocket Event
│
▼
Operations Interface
Workflow states:
PENDING
↓
MATCHING
↓
VERIFYING
↓
INVESTIGATING
↓
RESOLVED
Or:
INVESTIGATING
↓
ESCALATED
The AI system is treated as an external dependency that can fail.
Python AI Service
│
│ Timeout / Failure
▼
Go Circuit Breaker
│
▼
Fallback Policy
│
▼
HUMAN REVIEW
RAZE fails closed, not open.
An unavailable AI model must never result in uncontrolled financial automation.
Financial state is managed transactionally.
RAZE uses:
- PostgreSQL transactions
- Optimistic locking
- Row-level locking where required
- Idempotency keys
- Versioned state transitions
Example:
Transaction Version = 7
Worker A → reads version 7
Worker B → reads version 7
Worker A → commits version 8
Worker B → stale version detected
→ retry / reject
This prevents conflicting state changes from agents or human operators.
Every financial decision records:
timestamp
reconciliation_id
transaction_id
source_records
agent
action
confidence
evidence
decision
previous_state
new_state
actor
policy_version
model_version
data_version
Example:
REC_9021
Decision:
RECOMMEND_MATCH
Confidence:
0.92
Policy:
risk-policy-v3
Model:
investigator-v2
State:
INVESTIGATING → REVIEW
| Layer | Technology |
|---|---|
| Frontend | Next.js |
| Language | TypeScript |
| UI | Tailwind CSS + shadcn/ui |
| Backend | Go |
| HTTP | Chi / Gin |
| Internal RPC | gRPC + Protocol Buffers |
| Async Processing | Redis + Asynq |
| Database | PostgreSQL |
| Vector Search | pgvector |
| AI Service | Python + FastAPI |
| Agent Orchestration | LangGraph |
| Machine Learning | scikit-learn |
| Deep Learning | PyTorch |
| Policy Learning | Stable-Baselines3 |
| Fuzzy Matching | RapidFuzz |
| Embeddings | Sentence Transformers |
| Containerization | Docker |
RAZE enforces strict autonomy boundaries.
Financial arithmetic and critical validation remain deterministic.
Autonomous recommendations require supporting evidence.
Agents cannot directly mutate financial records.
Low-confidence decisions are routed to review or escalation.
Operators can approve, reject, override, or manually resolve recommendations.
Repeated requests cannot silently create duplicate financial operations.
AI failures fall back to safe human review.
Every state-changing operation is recorded.
The buildathon implementation uses:
- Razorpay Test Mode
- Controlled synthetic financial data
No production financial transactions are required.
Transaction
│
▼
Data Normalization
│
▼
Deterministic Checks
│
▼
Candidate Retrieval
│
▼
Evidence Construction
│
▼
Agentic Investigation
│
▼
Confidence Estimation
│
▼
Risk Policy
│
┌───────────┼───────────┐
▼ ▼ ▼
MATCH REVIEW ESCALATE
│ │ │
└───────────┼───────────┘
▼
Human Feedback
│
▼
Experience & Calibration
│
▼
Audit Trail
The system is designed to run as independent services.
Internet
│
▼
Next.js Frontend
│
▼
Go API Service
│ │
▼ ▼
PostgreSQL Redis
│ │
│ ▼
│ Asynq Worker
│ │
▼ ▼
pgvector Python AI Service
Services are containerized using Docker. A containerized stack is available via docker compose up --build (PostgreSQL, Go API, Python AI), but the containerized API does not seed benchmark data or drive the interactive session — for a complete, self-contained run use the launchers described in How to Run.
RAZE treats financial autonomy as a controlled systems problem.
Deterministic systems establish truth.
Machine learning ranks possibilities.
Agents investigate ambiguity.
Evidence makes decisions auditable.
Confidence controls autonomy.
Humans resolve uncertainty.
Feedback improves future decisions.
Adaptive policies optimize intervention.
Go protects the financial control plane.
Python provides probabilistic intelligence.
The system fails closed when AI becomes unavailable.
RAZE is an agentic financial reconciliation system combining:
- Deterministic financial controls
- Evidence-grounded AI investigation
- Confidence-aware automation
- Human-in-the-loop decision making
- Risk-sensitive policy learning
- Multi-record reconciliation
- Auditability
- Production-oriented distributed systems
Raze the backlog. Resolve the discrepancy. Prove the decision.
Apache-2.0