🛡️ Settlement Sentinel

Autonomous B2B Multi-Rail Settlement Copilot & Invariant Financial Operations Sentinel
From financial signal to execution — AI wired into real banking and on-chain payment rails. Scan, score, size, and route with zero hallucinations.

---

⚡ Overview

Settlement Sentinel is an institutional-grade, full-stack autonomous financial operations copilot. It eliminates the manual reconciliation drag, arithmetic calculation errors, wire fraud, and liquidity crunches that plague modern B2B finance and treasury teams.

By combining the agentic orchestration of Nous Hermes-3 ReAct loops with a hardened, deterministic neuro-symbolic invariant engine, Settlement Sentinel ensures that no LLM ever calculates numbers or mutates balances directly. Instead, the model acts as an intelligent workflow coordinator while pure TypeScript invariant rules enforce mathematical consistency, ISO banking standards, and cashflow safety limits.

---

🎯 The Real B2B Problems Solved

1. Arithmetic Invoice Overcharges & Math Variances:
   ~12% of commercial invoices contain subtotal, tax rate, or rounding errors that slip past manual accounting reviews. Settlement Sentinel validates Total = LineItems + Tax - Discount with sub-cent precision, instantly quarantining unauthorized overcharges (e.g. flagging a €364.75 overcharge on €8,475 cloud invoices).
2. Wire Transfer Fraud & Forged IBANs:
   When supplier emails are compromised and bank accounts altered, manual AP teams risk wiring millions to fraudulent accounts. Settlement Sentinel executes the international ISO-7064 Mod-97 remainder checksum on every bank account number before dispatch.
3. Liquidity Buffer Breaches & Cashflow Crunches:
   Batch payouts can dangerously deplete working capital right before payroll or tax obligations. Settlement Sentinel dynamically simulates 30-day cash runway and strictly enforces a minimum safety reserve ($20,000 default). Any batch proposal threatening the safety reserve is automatically halted (HOLD_FOR_MANUAL_REVIEW).
4. Forfeited Early-Payment Discounts (%37+ APR Yield Loss):
   Suppliers frequently offer terms such as "2/10 Net 30" (2% discount if paid within 10 days). Manually approved invoices routinely miss this window. Settlement Sentinel calculates the annualized yield and captures high-yield discounts (>30% APR) whenever liquidity permits.

---

🏗️ The 4-Stage Autonomous Pipeline

Settlement Sentinel executes transactions using an institutional 4-Stage Execution Loop:

   [ STAGE 1: SCAN ]          [ STAGE 2: SCORE ]          [ STAGE 3: SIZE ]          [ STAGE 4: ROUTE ]
 ┌──────────────────────┐   ┌──────────────────────┐   ┌──────────────────────┐   ┌──────────────────────┐
 │ • Ingest Invoices    │   │ • Sum(Lines) = Total │   │ • Safety Buffer ($20k│──>│ • Multi-Rail Dispatch│
 │ • Bank Feeds (Stripe)│──>│ • Tax Rate Invariant │──>│ • 30D Cash Runway    │   │   (SEPA/Faster/Base) │
 │ • Multi-Currency Bal │   │ • ISO-7064 IBAN Mod97│   │ • Early-Pay APR ROI  │   │ • SHA-256 Receipt    │
 │   (EUR/GBP/USD/USDC) │   │ • Quarantine Flags   │   │ • Liquidity Caps     │   │ • Ledger Confirmed   │
 └──────────────────────┘   └──────────────────────┘   └──────────────────────┘   └──────────────────────┘
                                        ▲
                                        │
                        [ HERMES-3 ReAct REASONING ENGINE ]
                        <thought> ... Chain-of-Thought ... </thought>
                        <tool_call> { "name": ..., "arguments": ... } </tool_call>
                        <tool_response> { "name": ..., "content": ... } </tool_response>

1. SCAN (scan_unsettled_ledger)

Ingests pending multi-currency invoices (EUR, GBP, USD, USDC), live bank statement feeds, and marketplace settlement streams (Stripe Connect, Trendyol, Barclays corporate wires, Base L2).

2. SCORE (reconcile_and_score_invoices)

Applies strict mathematical invariants: Total = Sum(LineItems) + VAT. Runs the ISO-7064 Mod-97 remainder algorithm on counterparty IBANs. Automatically isolates arithmetic variances and fraudulent accounts into quarantine.

3. SIZE (evaluate_cashflow_guardrails)

Simulates 30-day cash runway and evaluates working capital guardrails. Strictly enforces the minimum safety buffer and captures high-yield early-payment discounts.

4. ROUTE (route_settlement_batch)

Dispatches approved batches across designated settlement venues:

• SEPA Instant (EUR European Banking)
• UK Faster Payments (GBP UK Domestic Wires)
• Base USDC (Instant Low-Fee On-Chain Stablecoin Settlement)
• ACH Standard (USD US Banking)

Mints a deterministic 66-character SHA-256 cryptographic receipt (0x...) for tamper-proof audit trails.

---

🔒 Zero-Hallucination Neuro-Symbolic Architecture

Generative AI models are notoriously prone to arithmetic inaccuracies and floating-point errors. In institutional finance, an off-by-one error or hallucinated digit causes catastrophic loss.

Settlement Sentinel completely eliminates this vulnerability:

• LLMs Orchestrate, Never Calculate: Hermes-3 operates strictly as a ReAct planner emitting structured <tool_call> instructions. It never mutates financial balances or evaluates formulas directly.
• Deterministic TypeScript Engines: All arithmetic assertions, VAT multiplications, ISO-7064 Mod-97 modulo operations, cash runway formulas, and SHA-256 digests run in hardened, deterministic TypeScript (src/lib/financial-engine.ts).
• Guardrail Veto Power: Even if a user prompts the LLM to "settle all invoices immediately," the guardrail engine detects if the safety reserve is breached or if an IBAN is corrupted, immediately overriding the LLM and halting execution.

---

💻 Tech Stack

• Framework: Next.js 14 (App Router, Server Actions, API Routes)
• Language: TypeScript 5.4 (Strict Type Checking)
• Styling: Tailwind CSS, Lucide React Icons
• Agent Framework: Nous Hermes-3 ReAct (ChatML format)
• Tool Protocol: FastMCP-compatible JSON tool schemas
• Audio: Web Audio API (Synthesized auditory UI feedback)
• Testing: Deterministic Node.js verification test suite (16 comprehensive tests)

---

🧪 Comprehensive Verification Suite

Run the full automated test suite verifying all invariants, IBAN modulo algorithms, guardrails, and cryptographic hashes:

npm test

Output:

=================================================
  SETTLEMENT SENTINEL — VERIFICATION SUITE       
=================================================

  ✓ PASS: Invoice Math Invariant: Valid Subtotal + Tax = Total passes with 0 discrepancy
  ✓ PASS: Invoice Math Invariant: Detects arithmetic overcharge/variance
  ✓ PASS: ISO-7064 Mod-97: Valid European and UK IBAN formats pass checksum
  ✓ PASS: ISO-7064 Mod-97: Corrupted or forged IBAN fails checksum verification
  ✓ PASS: Runway Guardrail: Approves settlement when safety reserve is protected
  ✓ PASS: Runway Guardrail: Blocks excessive batch settlement that violates safety buffer
  ✓ PASS: Early Discount APR: Computes annualized yield for '2/10 Net 30'
  ✓ PASS: Cryptographic Receipt: Produces deterministic 66-char hex digest (0x + 64 hex chars)
  ✓ PASS: Hermes ChatML Parser: Extracts <thought> and <tool_call> JSON correctly
  ✓ PASS: Multi-Currency FX: Normalizes EUR, GBP, USD, and USDC accurately to treasury base
  ✓ PASS: Inbound Feed Simulation: Ingesting Stripe deposit expands liquid runway
  ✓ PASS: Batch Discrepancy Isolation: Quarantines invalid items without blocking valid items
  ✓ PASS: Liquidity Guardrail Halt: Rejects batch execution when payout breaches $240,000 buffer
  ✓ PASS: Initial Mock Ledger: 4 invoices approved ($20,068.30) and exactly 2 quarantined
  ✓ PASS: Multi-Currency Ledger: Payouts decrement exact currency accounts
  ✓ PASS: Single Settlement Guard: Blocks settlement of fraudulent or excessive invoices

=================================================
  Tests completed: 16 passed, 0 failed
=================================================

---

🚀 Getting Started

1. Clone & Install

git clone https://github.com/abdullahbakis/settlement-sentinel.git
cd settlement-sentinel
npm install

2. Start Development Server

npm run dev

Open http://localhost:3000 in your browser.

3. Production Build

npm run build
npm run start

---

👤 Author

Abdullah Bakış

• GitHub: @abdullahbakis
• LinkedIn: linkedin.com/in/abdullahbakis
• Portfolio Projects:
  • smart-accounting: Production Next.js App Router, multi-channel marketplace settlements, invoice models.
  • hermes-customs-agent: Nous Hermes-3 ReAct loops, FastMCP schemas, mathematical assertions.
  • Aegis-AI-Governence-Agent: ISO-7064 IBAN validation, cryptographic SHA-256 audit ledger.

---

📄 License

This project is open-source and available under the MIT License.