Solution Architecture & System Design • Personal Fiduciary Agent

🛡️ System Architecture Overview

Air-Gapped Privacy Deterministic Math Core Local LLM (Metal GPU)

The Personal Fiduciary Agent is an institutional-grade financial intelligence engine engineered for Apple Silicon macOS. Unlike traditional fintech apps that stream confidential banking data to cloud servers or hallucinate arithmetic using generic LLMs, this harness enforces a strict Three-Tier Separation Architecture: 1. Air-Gapped Data Ingestion with automatic PII masking, 2. Zero-Hallucination Deterministic Python Core for all calculations (runway, tax traps, bills), and 3. Grounded Local AI Reasoning running on Apple Silicon Metal GPU with real-time Grounding Guardrails.

Full Solution Architecture Topology

Complete end-to-end data pipelines from bank statements to local AI inference

Interactive Vector Diagram

flowchart TB
    subgraph INGESTION["1. INGESTION & PRIVACY LAYER"]
        PDF["UK Bank PDF Statements
(NatWest, Barclays, HSBC)"] --> PDFP["On-Device PDF Parser
(pypdf in-memory extraction)"]
        CSV["Bank CSV Exports
(Revolut, Chase, Lloyds)"] --> CSVP["CSV Banking Importer"]
        TL["TrueLayer Open Banking API
(Read-Only Account Token)"] --> TLP["TrueLayer Sync Client"]
        WISE["Wise Multi-Currency API
(Direct Read-Only Token)"] --> WCL["Wise Sync Client"]
        
        PDFP --> PII["PII Privacy Shield
• Sort Code: ••-••-XX
• Account: ••••XXXX"]
        CSVP --> PII
        TLP --> PII
        WCL --> PII
    end

    subgraph STORAGE["2. LOCAL AIR-GAPPED STORAGE"]
        PII --> DB[("SQLite Engine (data/financial.db)
• accounts
• transactions
• recurring_bills
• net_worth_snapshots
• llm_traces
• oauth_tokens (90d Refresh Tokens)
• credit_profile (CRA Scores & Electoral Roll)")]
    end

    subgraph CORE["3. DETERMINISTIC PYTHON CORE (ZERO MATH HALLUCINATION)"]
        DB --> TP["Transaction Profiler
• 30-Day Living Burn Rate
• Exact Liquid Runway Days
• Inbound Funding Patterns"]
        DB --> WD["Financial Watchdog
• Subscription Detection
• Stealth Price Hikes
• Duplicate Charge Audits"]
        DB --> TAX["UK Tax Optimizer
• 60% Marginal Tax Trap
• PSA Interest Drag
• SIPP Pension Sacrifice"]
        DB --> SWEEP["Smart Sweeper Engine
• 1st-of-Month Float Plan
• Consumer Rights 2015 Notices"]
        DB --> NW["Whole Balance Sheet
• Multi-Asset Net Worth
• Class Allocation (Cash/ISA/Pots)"]
        DB --> CREDIT["Credit & Affordability Engine
• FCA MCOB 11 Cash Flow (UMI/DTI)
• BNPL & Returned DD Radar
• 4.5x Mortgage Capacity & Stress
• 0–100 Readiness Score"]
    end

    subgraph AI["4. LOCAL OLLAMA REASONING & GUARDRAIL PIPELINE (100% PRIVATE)"]
        TP --> CTX["Financial Context Aggregator"]
        WD --> CTX
        TAX --> CTX
        SWEEP --> CTX
        NW --> CTX
        CREDIT --> CTX

        WEB["Multi-Tier Web Knowledge Engine
• Tier 1: Statutory HMRC Schedules
• Tier 2: Google Search / Serper API
• Tier 3: Live UK Organic Web Search"] --> CTX
        VRAG["Local Semantic Vector RAG
• Statutory HMRC Rules (ISA, SIPP, CGT)
• FCA MCOB 11 Guidelines
• Cosine Similarity (TF-IDF weighted)"] --> CTX
        WEB --> TOOL_OBS["Tool Execution Tracker
• Latency (ms), URL/Source, Payload
• tools_used_json stored in trace"]
        VRAG --> TOOL_OBS
        TOOL_OBS --> TRACE

        CTX --> PROMPT["Grounded Dynamic Prompt
(Pruned context: ~300 tokens)"]
        DB --> TXR["Itemised Transaction Retriever
• Bank filter (revolut / wise / natwest)
• 'last N' count detection
• Numbered newest-first rows"]
        TXR --> PROMPT

        PROMPT --> PII_ANON["Reversible PII Anonymizer
• Sort Codes: [SORT_CODE_1]
• Account Nums: [ACCOUNT_NUM_1]
• Lossless Roundtrip Deanonymization"]
        PII_ANON --> LLM_CLIENT["Unified LLM Client"]
        
        LLM_CLIENT -->|"Primary Default (100% Offline)"| OLLAMA["Ollama Local Engine (:11434)
(qwen3.5:4b / llama3.2 on Metal GPU)
• think: false (Sub-second)
• keep_alive: 0 (Zero RAM leak)"]
        LLM_CLIENT -.->|"Alternative Local"| LMSTUDIO["LM Studio Local Endpoint (:1234)
(Meta-Llama-3.1-8B)"]
        LLM_CLIENT -.->|"Enterprise AI Gateway (Opt-in)"| GATEWAY["AI Gateway / LiteLLM Proxy (:4000)
(OpenAI-compatible router & cache)"]
        LLM_CLIENT -.->|"Dormant Adapter (Opt-in only)"| GEMINI["Google Gemini Cloud API
(Zero egress by default)"]

        OLLAMA --> REACT["Autonomous ReAct Agent Engine
• Thought → Action → Observation
• Dynamic MCP Tool Calling
• Max 4 steps safety ceiling"]
        REACT --> PREFLIGHT["Pre-Flight Fiduciary Evaluator & Self-Correction Gate
• Extracts all £, %, days
• Audits FCA Consumer Duty & Invariants
• Auto-Repairs Hallucinations Pre-Delivery (<2ms)"]
        LMSTUDIO -.-> PREFLIGHT
        GATEWAY -.-> PREFLIGHT
        GEMINI -.-> PREFLIGHT

        PREFLIGHT --> TRACE["Observability Logger
• Latency (ms)
• Grounding Score
• llm_traces Table"]
        TRACE -.->|"On demand: ./f judge"| JUDGE["Layer 2: LLM-as-a-Judge
(Ollama :11434 with think: false)
• Faithfulness / Relevance / Fiduciary
• Auto-unloaded after evaluation"]
        JUDGE -.->|"judge_result_json"| TRACE
        TRACE -.->|"./f eval"| BENCHMARK["Enterprise EVAL Benchmark Suite
• 6-Dimension Golden Dataset
• Grade A+ Production Gate"]
    end

    subgraph INTERFACES["5. CLIENT PRESENTATION INTERFACES"]
        PREFLIGHT --> FASTAPI["FastAPI Local Server (127.0.0.1:8080)"]
        TRACE --> FASTAPI

        FASTAPI --> MACAPP["Native macOS App
(/Applications/Fiduciary.app)"]
        FASTAPI --> BROWSER["Local Web Dashboard
(http://localhost:8080)
• Live Transactions tab
• Credit & Borrowing tab
• Traces & EVAL modal"]
        FASTAPI --> CLI["Interactive Terminal CLI
(./f eval, ./f react, ./f rag, ./f copilot --react, ./f tx, ./f judge)"]
    end


    style INGESTION fill:#064e3b,stroke:#059669,stroke-width:2px,color:#ecfdf5
    style STORAGE fill:#1e293b,stroke:#475569,stroke-width:2px,color:#f8fafc
    style CORE fill:#1e1b4b,stroke:#6366f1,stroke-width:2px,color:#e0e7ff
    style AI fill:#581c87,stroke:#a855f7,stroke-width:2px,color:#faf5ff
    style INTERFACES fill:#0f172a,stroke:#38bdf8,stroke-width:2px,color:#f0f9ff

1. Complete Privacy Air-Gap

Confidential PDF statements and transaction records are parsed and stored locally. Zero raw financial data ever traverses the internet.

2. Deterministic Accuracy

The AI never calculates balances or taxes. Pure Python mathematical algorithms calculate verified figures and inject them as hard facts.

3. Continuous Guardrails

The Grounding Auditor scans every generated response, verifying that every financial citation matches ground truth.

Ingestion Pipeline & Query Execution Sequences

Sequence diagrams detailing the zero-leakage statement parsing and copilot query lifecycles

Sequence Flow

A. PDF Statement Parsing & PII Redaction Flow

sequenceDiagram
    autonumber
    actor User as User (Drag & Drop)
    participant UI as Web / Fiduciary.app
    participant API as FastAPI (/api/upload)
    participant Parser as PDFStatementParser (pypdf)
    participant Reconciler as Balance Delta Reconciler
    participant Shield as PII Redactor
    participant DB as SQLite (financial.db)

    User->>UI: Drops NatWest Statement PDF
    UI->>API: POST /api/upload (Multipart Bytes)
    API->>Parser: parse_pdf(filename, raw_bytes)
    Note over Parser: 100% In-Memory Extraction.
No temp files on disk.
    Parser->>Shield: Extract Sort Code & Account Number
    Shield->>Shield: Auto-Mask: ••-••-30 & ••••7715
    Parser->>Reconciler: Extract Multi-Column Table & Balances
    Reconciler->>Reconciler: Delta Math: Bal[k] - Bal[k-1] = True Amount
    Note over Reconciler: Discards 'Brought Forward' rows.
Eliminates Debit/Credit guesswork.
    Reconciler->>DB: Upsert Institution ('natwest', 'NatWest')
    Reconciler->>DB: Upsert Account (acc_natwest_imported, masked PII)
    Reconciler->>DB: Insert Categorized Transactions
    DB-->>API: Commit Success (8 txs, £7,428.47 balance)
    API-->>UI: Return JSON Summary
    UI-->>User: Instant Dashboard Refresh

B. Air-Gapped Copilot Query & Grounding Verification Flow

sequenceDiagram
    autonumber
    actor User as User (Query)
    participant Guard as PromptGuard (0ms Filter)
    participant Copilot as AICopilotEngine
    participant MCP as MCP Gateway (7 Standard Tools)
    participant DB as SQLite (financial.db)
    participant PythonCore as Deterministic Profiler & Watchdog
    participant Ollama as Local Ollama (:11434 / Metal GPU)
    participant Guardrail as GroundingAuditor
    participant Tracer as Observability Tracer

    User->>Guard: "What is my emergency fund buffer?"
    Guard->>Guard: Inspect for injection, DAN jailbreaks, delimiter tokens
    Guard-->>Copilot: Sanitized Query (is_safe: true, risk: 0.0)
    Copilot->>MCP: resolve_and_ground(query)
    MCP-->>Copilot: Grounded Market Benchmarks & BoE Data
    Copilot->>DB: Fetch Accounts, 30d Transactions, Bills
    DB-->>PythonCore: Raw Financial Records
    PythonCore->>PythonCore: Compute exact metrics:
Target Buffer: £8,263.80
Liquid Capital: £7,462.12
Runway: 81.3 Days (Shortfall £801.68)
    PythonCore-->>Copilot: Pre-calculated Ground Truth
    Copilot->>Copilot: Wrap context in [verified_financial_context]
Apply anti-refusal system directives
    Copilot->>Ollama: POST /api/chat (model: qwen3.5:4b, think: false, keep_alive: 0)
    Note over Ollama: 100% On-Device Offline Inference on Metal GPU.
Zero RLHF refusal, exact math output.
Total latency ~1.2s.
    Ollama-->>Copilot: Grounded Natural Language Response
    Copilot->>Guardrail: audit(response, system_prompt)
    Guardrail->>Guardrail: Validate £8,263.80, £7,462.12, 81.3 days against ground truth
    Guardrail-->>Tracer: Status: VERIFIED_GROUNDED (Score: 1.0)
    Tracer->>DB: INSERT INTO llm_traces (includes tools_used_json)
    Copilot-->>User: Grounded Fiduciary Output & Zero Refusal

C. On-Demand LLM-as-a-Judge Evaluation (16GB-Safe)

sequenceDiagram
    autonumber
    actor User as User (./f judge)
    participant Judge as LLMJudge (judge.py)
    participant Ollama as Local Ollama (:11434 / Metal GPU)
    participant DB as SQLite (llm_traces)

    User->>Judge: Evaluate latest trace (./f judge)
    Judge->>DB: Load query, ground-truth context, copilot response
    Judge->>Ollama: POST /api/generate (format: json, think: false, keep_alive: 0, num_ctx: 4096)
    Note over Ollama: Evaluates independently with think: false.
Unloaded from RAM immediately after answering (keep_alive: 0).
    Ollama-->>Judge: JSON: Faithfulness (1.0), Relevance (1.0), Fiduciary Soundness (1.0), Verdict: PASSED
    Judge->>Judge: Overall Score = 0.45 F + 0.35 S + 0.20 R = 1.00
    Judge->>DB: UPDATE llm_traces SET judge_result_json
    Judge-->>User: ⚖️ LLM-AS-A-JUDGE VERDICT: PASSED (Overall: 1.00)

Deterministic Financial Core Modules

Pure Python algorithmic engines executing mathematical formulas to the exact penny

⏱️ Transaction Profiler (profiler.py) Runway Engine

Aggregates 30-day and 90-day transactions to compute granular outflow burn rates. Divides total liquid cash by daily living expenses to calculate exact liquid runway days. Flags recurring inbound top-ups to identify cognitive cash-flow friction.

runway_days = round(liquid_gbp / daily_burn, 1)
monthly_float = round(monthly_burn * 1.0, 2)

🚨 Financial Watchdog (watchdog.py) Anomaly Detector

Maintains strict keyword boundaries (\b) and category exclusion lists to identify genuine recurring subscriptions (British Gas, TV Licence, Anthropic). Detects stealth price hikes (>5% jump) and duplicate card charges within 24 hours.

is_hike = latest > prev * 1.05 and (latest - prev) >= 0.50
is_dup = c1.merchant == c2.merchant and c1.amt == c2.amt and abs(c1.dt - c2.dt) <= 1d

🇬🇧 UK Tax Optimizer (tax_optimizer.py) HMRC Statutory Logic

Models UK income tax bands (Basic 20%, Higher 40%, Additional 45%). Calculates the punitive 60% marginal tax trap between £100,000 and £125,140 caused by Personal Allowance tapering, and computes the exact pension sacrifice required to restore it.

taper_loss = min(12570, max(0, (gross_income - 100000) / 2))
effective_rate = 60.0% if 100000 < income <= 125140

⚡ Smart Automation & Sweeper (automation.py) Cashflow Automation

Detects idle cash drag in 0% current accounts and calculates the optimal sweep into 4.87% Flexible Cash ISAs. Generates statutory cancellation notices under the UK Consumer Rights Act 2015 with 1-click clipboard export.

sweepable_cash = max(0.0, liquid_gbp - 30d_burn_buffer)
projected_annual_yield = sweepable_cash * 0.0487

🏦 Credit & Affordability Engine (credit_affordability.py) FCA MCOB 11 Underwriter

Underwrites household creditworthiness according to UK Open Banking standards. Detects monthly payroll, living necessities, and contractual debt to compute Uncommitted Monthly Income (UMI) and Debt-to-Income (DTI). Scans 90-day history for BNPL instalments (Klarna/Clearpay) and returned direct debits, calculates 4.5x gross mortgage capacity with 7.5% stress testing, and maintains an air-gapped local CRA profile.

UMI = net_monthly_income - (fixed_needs + committed_debt)
mortgage_capacity = (gross_annual * 4.5) - (annual_debt * 3.5)
readiness_score = cashflow(40) + dti(20) + hygiene(25) + identity(15)

Observability & Grounding Guardrails Pipeline

Real-time verification ensuring no hallucinated figures reach the user

How the Grounding Auditor & Local Evaluation Work

Every time the AI produces a response (via local Ollama on Apple Silicon Metal GPU), the raw completion is intercepted by the GroundingAuditor before being returned to the UI or terminal.

1. Entity Extraction: Scans the response using regular expressions for all currency figures (e.g. £7,455.73, £50.00), percentages (4.87%, 3.75%), and runway days.
2. Ground-Truth Matching: Checks whether each cited figure was present in the deterministic context passed into the system prompt. Allows mathematical equivalents (e.g. rounded integers).
3. In-Line Pre-Flight Self-Evaluation Gate: Executes before the response is delivered to the consumer (<2ms). Audits numerical grounding, UK FCA Consumer Duty invariants (emergency buffer preservation, non-predatory products, statutory tax bounds), and detects negative premise baiting.
4. Autonomous Pre-Delivery Self-Correction: If unverified claims or invariant breaches are detected, the critic loop feeds targeted diagnostic feedback back to the LLM for a rapid repair pass. If unverified estimates remain, transparent fiduciary disclaimers are attached so the customer is never misled.
5. Immutable Trace Logging: Records the full trace with latency (ms), model identifier, provider (local, gateway, gemini), prompt, response, preflight evaluation result, and tools used to the llm_traces table.
6. Enterprise EVAL Benchmark Suite (./f eval): A production Forward Deployment Engineering (FDE) test harness auditing 6 core dimensions: Grounding Precision, FCA Consumer Duty, Negative Fact Resistance, Red-Teaming Injections, Ledger Reconciliation, and Latency SLAs. Delivers Grade A+ institutional verification.
7. Layer 2 - Independent LLM-as-a-Judge: ./f judge audits interactions on demand using an independent local model on Ollama. Enforces keep_alive: 0 to automatically unload models from Apple Silicon unified memory immediately after scoring, keeping RAM 70%+ free.
8. Tool Execution & Provenance Tracking: Every web scraping call (BoE 3.75%), retail market feed (Trading 212 4.87%, First Direct 7.00%), and database transaction query generates structured telemetry (tool_name, source, latency_ms, summary). Stored in tools_used_json and inspectable via ./f tools, ./f traces --detail <ID>, or the Web Dashboard.

Live Trace Inspection Schema

id: "tr_2d5a49d95318"

caller: "copilot"

provider: "local"

model: "qwen3.5:4b"

latency_ms: 1194.5

tools_used: [{"tool": "fetch_top_savings_and_isas", "lat_ms": 0.0}]

grounding_status: "VERIFIED_GROUNDED"

grounding_score: 1.0 (100%)

judge_verdict: "PASSED (Score: 1.00)"

verified_figures: ["7.00%", "4.87%", "£2,236.50", "300"]

unverified_figures: []

SQLite Entity Relationship & Data Model

Embedded database structure stored locally at data/financial.db

erDiagram
    institutions ||--o{ accounts : "has"
    accounts ||--o{ transactions : "contains"
    
    institutions {
        string id PK
        string name
        string country
        string status
        timestamp authorized_at
    }

    accounts {
        string id PK
        string institution_id FK
        string name
        string account_type
        string asset_class
        string currency
        string sort_code "Masked Sort Code"
        string account_number "Masked Account Number"
        real current_balance
        real available_balance
        timestamp updated_at
    }

    transactions {
        string id PK
        string account_id FK
        string booking_date
        real amount
        string currency
        string counterparty_name
        string description
        string category
        integer is_recurring
    }

    recurring_bills {
        string id PK
        string merchant
        string category
        real expected_amount
        string frequency
        string last_date
        string next_due_date
        integer is_active
    }

    net_worth_snapshots {
        integer id PK
        string snapshot_date
        real total_assets
        real total_liabilities
        real net_worth
        real liquid_assets
        string breakdown_json
    }

    llm_traces {
        string id PK
        string timestamp
        string caller
        string provider
        string model
        real latency_ms
        string user_prompt
        string system_prompt
        string response
        string grounding_status
        real grounding_score
        string unverified_tokens_json
        string judge_result_json "LLM Judge verdict"
        string tools_used_json "Tool execution metadata"
    }

    copilot_chat {
        integer id PK
        string role
        string content
        string metadata_json
        timestamp created_at
    }

    oauth_tokens {
        string provider PK
        string access_token
        string refresh_token
        timestamp expires_at
        timestamp updated_at
    }

    credit_profile {
        integer id PK
        integer experian "Experian score (0-999)"
        integer equifax "Equifax score (0-1000)"
        integer transunion "TransUnion score (0-710)"
        integer electoral_roll "Electoral roll registered"
        string notes
        timestamp updated_at
    }

🗄️ Storage Engine Analysis: Why SQLite? (SQLite vs DuckDB vs PostgreSQL)

Architectural decision rationale and pluggable storage adapter trade-offs

Evaluation Criteria	SQLite (Current Choice)	DuckDB (Analytical Vector)	PostgreSQL (Enterprise SaaS)
Deployment Model	Embedded, zero-daemon, single file	Embedded, in-process columnar	Client-server daemon (Docker/service)
Memory Footprint	~0 MB idle (critical for 16GB Mac)	Moderate buffer pool memory	High (shared buffers + connection pool)
Air-Gap & Privacy	100% local APFS file, zero network ports	100% local file / Parquet lake	Network TCP ports, credential surface
Query Latency	< 0.1 ms (instant transactional lookups)	< 0.5 ms (vectorized scan over millions)	1.0 – 5.0 ms (network roundtrip)
Special Superpower	Zero dependency (Python standard lib)	Direct Parquet query + native VSS vector search	Multi-tenant RLS, pgvector, TimescaleDB
When to Switch?	Default for single-user local fiduciary	Switch if storing 500K+ txs or vector embeddings	Switch if deploying as a hosted SaaS / multi-user portal

Why SQLite for Fiduciary Agent? On a 16GB Apple Silicon Mac running local LLMs (Ollama qwen3.5:4b), unified RAM is precious. SQLite requires zero background processes, zero ports, and stores encrypted banking records directly in data/financial.db.

When should you use DuckDB? DuckDB is exceptional if you export decades of tick data from brokers (Interactive Brokers, TradingView) or want to execute local vector semantic search across transaction descriptions using DuckDB's vss extension.

When should you use Postgres? Postgres is the standard if migrating this harness into a multi-tenant family-office SaaS platform with concurrent web worker writes, row-level security (RLS), and pgvector search in cloud infrastructure.

Technical Privacy & Air-Gap Verification

You can physically verify that zero financial data leaves your laptop using two standard macOS technical procedures:

1. Offline Air-Gap Test (Airplane Mode)

Turn off Wi-Fi on your Mac completely. Run:

./f copilot "What is my liquid balance?"

The agent answers immediately via local Ollama on Metal GPU with zero network connectivity.

2. Network Socket Inspection

Check active TCP connections from Python and local runners:

lsof -iTCP -sTCP:ESTABLISHED -n -P | grep -E "python|8080|11434|1234"

All connections are local loopbacks (127.0.0.1). Zero outbound external packets.

Financial Data Engineering & Closed-Loop Reconciliation Architecture

Formal engineering invariants, cryptographic provenance, stateful narrative buffering, and two-stage SLM critic verification

Discrepancy ≡ £0.00

flowchart TD
    subgraph STAGE1["1. RAW STATEMENT INGESTION & CRYPTOGRAPHY"]
        RAW["Raw PDF / CSV Bank Statement"] --> HASH["Compute SHA-256 Batch Fingerprint
file_hash_sha256 = sha256(raw_bytes)"]
        HASH --> BATCH["Register statement_batches Record
Status: PENDING"]
    end

    subgraph STAGE2["2. STATEFUL NORMALIZATION & NARRATIVE BUFFER"]
        BATCH --> TOKEN["Token Lookahead Buffer
• Multi-line narrative stitching
• Overdraft limit bounds filtering"]
        TOKEN --> DATEP["Stateful Same-Day Date Forward-Propagation
current_date binds to trailing sub-rows"]
        DATEP --> DELTA["Running Balance Delta Direction Solver
ΔB = B(t) - B(t-1)
+Inflow if ΔB > 0, -Outflow if ΔB < 0"]
    end

    subgraph STAGE3["3. CLOSED-LOOP DOUBLE-ENTRY SOLVER"]
        DELTA --> SOLVER["Double-Entry Invariant Proof
Opening + ΣInflows - ΣOutflows == Closing
Δ = Calculated - Actual Closing"]
        SOLVER -->|Discrepancy == 0.00| REC["Status: RECONCILED / CLOSING_VERIFIED"]
        SOLVER -->|Discrepancy != 0.00| GAP["Status: UNRECONCILED_GAP (Alert)"]
    end

    subgraph STAGE4["4. IDEMPOTENT PERSISTENCE"]
        REC --> UPSERT["Deterministic Transaction Fingerprinting
id = tx_sha256(account:date:amount:norm_desc)
ON CONFLICT(id) DO UPDATE (Zero Duplicates)"]
        UPSERT --> SQLITE[("Air-Gapped SQLite DB
data/financial.db")]
    end

    subgraph STAGE5["5. TWO-STAGE CRITIC EVALUATION (SLM ISOLATION)"]
        SQLITE --> COPILOT["Stage 1: Generative Copilot
Qwen 3.5 4B (Local Metal GPU)"]
        COPILOT --> CRITIC["Stage 2: Independent Grounded SLM Judge
Llama 3.2 3B (Faithfulness & Math Audit)
keep_alive=0 Metal VRAM Purge"]
        CRITIC --> TRACE["Audit Provenance & Observability Log"]
    end

📐 Double-Entry Mathematical Invariant

Retail financial applications commonly sum rows independently, causing rounding errors and phantom money when bank statements omit explicit negative signs or roll pending card authorizations.

Opening + Σ Inflows - Σ Outflows ≡ Closing Balance (Δ ≡ £0.00)

If a single transaction is missed, duplicated, or mis-signed, the batch status is immediately flagged as UNRECONCILED_GAP with the exact penny variance recorded in SQLite for auditing.

🔐 Cryptographic Provenance & Idempotency

Financial data pipelines must be resilient to repeated ingestion of overlapping statements (e.g. downloading May-June and then June-July statements).

tx_id = "tx_" + sha256(account | date | amount | norm_description)[:16]

Every statement batch logs its raw SHA-256 fingerprint in statement_batches. Transactions are upserted via deterministic content keys, guaranteeing 100% idempotent deduplication.

🧠 Stateful Token Normalization Buffer

UK statements (NatWest, Barclays, HSBC) frequently wrap lengthy payment narratives (e.g. "BILL PAYMENT FROM J BLOGGS REFERENCE EXPENSES JULY") across 2 to 4 physical PDF lines with no date or balance on trailing rows.

The parser maintains a stateful narrative accumulator that binds orphan description lines to the current active transaction until the next transaction header or balance delta is encountered, while strictly pruning legal footers ("Overdraft Limit £1,000").

⚖️ Two-Stage Critic: Grounded SLM Judge Separation

Standard LLM architectures suffer from confirmation bias when an agent judges its own responses. We enforce an institutional separation of concerns:

Generative Copilot: Qwen 3.5 4B generates user summaries and tactical recommendations.
Grounded Critic: Llama 3.2 3B independently evaluates claims against deterministic SQLite ground truth.
Zero-Leak Metal VRAM Purge: Evaluator uses keep_alive=0, releasing Unified Memory immediately after evaluation.

Mobile Phone Linking & Biometric FaceID Architecture

Zero-compromise security flow connecting mobile banking apps to the Mac host

Universal Link + Biometrics

Most UK banking apps (Lloyds, Revolut, Chase, HSBC, NatWest) mandate biometric hardware authentication (FaceID / TouchID) on a smartphone. The fiduciary agent bridges your phone and Mac host via a zero-egress local network architecture:

sequenceDiagram
    autonumber
    actor User as User (Mobile Phone)
    participant Phone as Mobile Browser (Safari/Chrome)
    participant Mac as Fiduciary Host (Mac LAN :8080)
    participant TL as TrueLayer Auth Gateway
    participant BankApp as Bank Native App (Lloyds/Revolut)

    User->>Phone: Open http://[mac-ip]:8080
    Phone->>Mac: GET / (Loads Responsive PWA Dashboard)
    User->>Phone: Tap "Connect Bank"
    Phone->>Mac: GET /truelayer/auth
    Mac-->>Phone: 302 Redirect to auth.truelayer.com
    Phone->>TL: Load Bank Selection
    User->>TL: Selects Bank (e.g. Lloyds)
    TL-->>Phone: Universal Link / App Scheme
    Phone->>BankApp: Deep link launches native banking app
    User->>BankApp: Biometric FaceID / Passcode Auth
    BankApp-->>TL: Grants 90-day read-only consent
    TL-->>Phone: 302 Redirect http://localhost:8080/truelayer/callback?code=AUTH_CODE
    Note over Phone: Mobile browser cannot reach localhost:8080
    User->>Phone: 1. Tap "Paste from Clipboard & Connect"
OR 2. Edit URL localhost -> [mac-ip]
    Phone->>Mac: POST /api/truelayer/exchange {code: "AUTH_CODE"}
    Mac->>TL: POST /connect/token (Candidate URI Matching)
    TL-->>Mac: 200 OK {access_token, refresh_token}
    Mac->>Mac: Store in oauth_tokens & trigger initial sync
    Mac-->>Phone: 200 OK {status: "success", accounts_synced: 2}
    Note over User,Phone: Live balances & transactions appear instantly

📱 The "Localhost Redirect" Invariant

Strict OAuth 2.0 specifications enforced by the UK Open Banking Implementation Entity (OBIE) and the FCA mandate that callback redirect URIs cannot contain wildcards or arbitrary dynamic LAN IPs.

Redirects must strictly match console-registered endpoints (e.g. http://localhost:8080/truelayer/callback). When a mobile banking app completes FaceID authentication, TrueLayer sends the browser back to localhost, which fails on mobile.

📋 1-Tap Clipboard Handoff Engine

We engineered a seamless 1-tap clipboard bridge: when redirected to the unroutable localhost URL, the user simply copies the URL in Mobile Safari and taps "📋 Paste from Clipboard & Connect" in the dashboard.

The frontend uses navigator.clipboard.readText() to extract the authorization code via regex and asynchronously posts it to /api/truelayer/exchange, eliminating all friction.

🔄 Multi-Candidate Token Exchange

OAuth token exchange strictly validates that the redirect_uri sent during token exchange matches the URI from authorization.

The backend tests multiple candidate redirect URIs in order (localhost:8080, 127.0.0.1:8080, and active LAN IPs) until TrueLayer accepts the token grant, guaranteeing 100% exchange reliability.

Enterprise Agentic Core: ReAct, PII Anonymizer & Local Vector RAG

Autonomous reasoning loop, cryptographic privacy boundaries, and embedded semantic knowledge retrieval

Agentic Workflow

A. Autonomous ReAct Reasoning & PII Lifecycle

sequenceDiagram
    autonumber
    actor User as Client Query
    participant Guard as Prompt Guard
    participant Anon as PII Anonymizer
    participant ReAct as ReAct Agent Engine
    participant MCP as MCP Tool Gateway
    participant RAG as Local Vector RAG
    participant LLM as Local Qwen 3.5 4B (Metal GPU)
    participant Tracer as Observability Tracer

    User->>Guard: "Check my grocery spend and ISA allowance for Sort Code 20-45-78"
    Guard->>Guard: Scan injection & delimiters (PASS)
    Guard->>Anon: Sanitize & inspect PII
    Anon->>Anon: Salt-indexed replace: 20-45-78 -> [SORT_CODE_1]
    Anon->>ReAct: Clean query + mapping token dict

    loop ReAct Multi-Step Trajectory (Max 4 turns)
        ReAct->>LLM: Generate Thought + Action
        LLM-->>ReAct: Thought: "Need grocery spend" | Action: query_spending_and_transactions
        ReAct->>MCP: call_tool("query_spending_and_transactions", {"query": "groceries"})
        MCP-->>ReAct: Observation: £342.15 (14 transactions)
        
        ReAct->>LLM: Generate next Thought + Action
        LLM-->>ReAct: Thought: "Need ISA allowance" | Action: vector_search_documents
        ReAct->>RAG: search("ISA statutory allowance limit", top_k=1)
        RAG-->>ReAct: Observation: £20,000 allowance, £4,000 LISA bonus
    end

    ReAct->>LLM: Synthesize Final Answer
    LLM-->>ReAct: Final Answer containing [SORT_CODE_1]
    ReAct->>Anon: deanonymize([SORT_CODE_1] -> 20-45-78)
    Anon-->>ReAct: Restored Grounded Answer
    ReAct->>Tracer: Record steps, latencies & tools to llm_traces
    ReAct-->>User: Complete Fiduciary Verdict & Guidance

🤖Autonomous ReAct Loop

Executes iterative Thought → Action → Observation steps. Rather than single-pass guessing, the agent dynamically interrogates databases, scrapes central bank rates, and inspects spending ledgers until reaching a verified conclusion.

🛡️Cryptographic PII Shield

Sort codes, account numbers, NINOs, card numbers, emails, and phone numbers are reversibly tokenized before any model invocation. Restored losslessly on return, guaranteeing zero raw credentials ever reach model context.

🔍Embedded Vector RAG

Embedded TF-IDF weighted cosine similarity index pre-seeded with HMRC ISA rules, pension schedules, CGT allowances, and FCA MCOB 11 underwriting guidelines. Operates in-process with 0 MB background daemon overhead.

🌐 Multi-Tier Web Knowledge Routing: Why DuckDuckGo & Google?

To balance 100% free offline privacy with accurate live internet intelligence, the web search engine uses an intelligent 3-tier cascade:

Tier 1: Statutory Fast-Path Instant exact HMRC allowance schedules (£20k ISA, £60k Pension, £3k CGT, PSA) in <0.1ms with zero network requests.

Tier 2: Google Search / Serper If GOOGLE_CSE_ID + GOOGLE_API_KEY or SERPER_API_KEY is set, routes queries directly to Google Search with UK geolocation (gl=uk).

Tier 3: Live Organic Web Search If no API key is provided, extracts live organic snippets from GOV.UK, HMRC, and NS&I via open HTML search without triggering anti-bot CAPTCHAs.