FinOS

Autonomous Multi-Agent Financial Operating System for Indian Retail Investors

Regulatory Disclaimer: FinOS is an educational and quantitative simulation tool, not a SEBI-registered investment advisory service. All financial calculations, tax regime comparisons, and autopilot trade-off analyses are strictly for informational and demonstration purposes.

---

⚡ Executive Summary

Most personal finance tools force users into one of two compromises: static spreadsheets that demand manual calculation, or generic LLM wrappers that hallucinate arithmetic, invent tax slabs, and fail basic compounding math.

FinOS solves this by strictly decoupling agentic semantic routing and natural language explanation from deterministic financial computation. Built specifically for the Indian financial context under the Finance Act 2024 / FY 2024-25, FinOS coordinates a swarm of 8 specialized LangGraph agents backed by audited mathematical engines, a hybrid BM25 + dense vector RAG pipeline, and biometric FIDO2 WebAuthn authentication.

---

🏗 Architecture & Swarm Topology

graph TB
    User(["User Query / WebSocket"]) --> Supervisor["Supervisor Agent<br/>(Dynamic Intent Routing & Guardrails)"]

    subgraph Specialized Sub-Agent Swarm
        Portfolio["Portfolio Agent<br/>(NSE Live Quotes, Newton-Raphson XIRR)"]
        Tax["Tax Agent<br/>(Finance Act 2024 / Slabs / LTCG / STCG)"]
        Debt["Debt Agent<br/>(Reducing-Balance EMI & Amortisation)"]
        Knowledge["Knowledge Agent<br/>(Hybrid RAG: BM25 + ChromaDB RRF)"]
        Goal["Goal Agent<br/>(Step-Up SIP Projection)"]
        Spend["Spend Agent<br/>(Zomato/Swiggy Anomaly Detection)"]
        Robo["Robo-Advisor Agent<br/>(Target Drift & Rebalancing Planner)"]
    end

    subgraph Deterministic Engines ["Zero-LLM Mathematical Core"]
        TaxEngine["Tax Engine: Section 115BAC, 87A Rebate, Cess"]
        DebtEngine["Amortisation Engine: Avalanche vs Snowball"]
        XIRREngine["XIRR Engine: Date-based Newton-Raphson"]
        RAGEngine["RAG Engine: Lexical BM25 + Vector Fusion"]
    end

    Supervisor -->|Parallel Dispatch| Portfolio & Tax & Debt & Knowledge & Goal & Spend & Robo

    Portfolio --> XIRREngine
    Tax --> TaxEngine
    Debt --> DebtEngine
    Knowledge --> RAGEngine

    Portfolio & Tax & Debt & Knowledge & Goal & Spend & Robo --> Merger["Output Merger / Autopilot Node<br/>(Multi-Objective Tradeoff Math)"]
    Merger --> FinalResponse(["Real-Time SSE Stream with Citations"])

Loading

Autopilot Prepay vs. Invest Tradeoff Engine

When a user asks: "Should I prepay my 8.75% home loan or invest in an equity mutual fund?", FinOS executes the following deterministic sequence:

sequenceDiagram
    autonumber
    actor User
    participant Router as Supervisor Agent
    participant Debt as Debt Agent
    participant Tax as Tax Agent
    participant Portfolio as Portfolio Agent
    participant Engine as Autopilot Tradeoff Engine
    participant Client as Frontend (SSE Stream)

    User->>Router: "Prepay ₹1L loan or invest in Nifty 50?" (Autopilot ON)
    par Parallel Sub-Agent Fetch
        Router->>Debt: Fetch outstanding balance (₹32.5L @ 8.75%)
        Router->>Tax: Fetch marginal bracket (30%) & Sec 24(b) deduction
        Router->>Portfolio: Fetch historical Nifty 50 CAGR (12%)
    end
    Debt-->>Engine: Loan parameters
    Tax-->>Engine: Marginal tax rate (30%) & LTCG rate (12.5%)
    Portfolio-->>Engine: Expected benchmark return
    Engine->>Engine: Post-Tax Loan Cost: 8.75% * (1 - 0.30) = 6.125%
    Engine->>Engine: Post-Tax Equity CAGR: 12% - 12.5% LTCG = 10.50%
    Engine->>Engine: Net Delta over 5Y tenure: +₹4.20 Lakh in favor of equity
    Engine-->>Client: Streamed Tradeoff Analysis + Sensitivity (-2%, base, +2%) + Disclaimer

Loading

---

📊 Benchmark & Quality Gate

Continuous evaluations run against a 35-case golden evaluation suite covering single-agent, multi-agent, adversarial, and boundary test cases.

Metric	Measured Value	Target SLA	Verification Method
Full Golden Suite Pass Rate	100.0% (35/35)	$\ge 80%$	make eval-full
Smoke Suite Pass Rate	100.0% (6/6)	$\ge 80%$	make eval
Offline Inference Latency	3.5 ms (smoke) / 10.8 ms (full)	$< 50\text{ ms}$	High-fidelity mock LLM
Hallucination Rate	0.0%	$< 5.0%$	Automated fact & citation checker
Agent Routing Accuracy	97.1% (full) / 100% (smoke)	$\ge 90%$	Dynamic supervisor intent classification
Pytest Unit/Hypothesis Suite	74 Passed (100%)	100%	make test
Code Coverage	70% overall (Core Tools: 81-98%)	$> 65%$	pytest --cov=src

---

🚀 Quick Start (Zero API Key Required)

FinOS is designed to be demonstrated immediately without configuring third-party LLM credentials.

1. Instant One-Command Offline Demo

# Clone the repository
git clone https://github.com/aimandhanani/FinOS.git
cd FinOS

# Install, seed mock data, and start stack in offline demo mode
make demo

Open http://localhost:5173 in your browser. Log in with the pre-seeded account demo@finos.ai / password123 or generate a local biometric WebAuthn passkey.

2. Developer Toolchain

# Run test suite with coverage report
make test

# Run code linters (Ruff for backend, Oxlint for frontend)
make lint

# Autoformat codebases
make format

# Run LLM quality gate smoke evaluation
make eval

# Start full stack in Docker Compose
make docker-up

3. Production Mode with Real LLMs

To connect FinOS to live cloud inference, create a .env.local file:

GROQ_API_KEY=gsk_your_groq_api_key_here
FINOS_DEMO_MODE=false
DATABASE_URL=sqlite:///finos.db
WEBAUTHN_RP_ID=localhost
WEBAUTHN_ORIGIN=http://localhost:5173

---

🧮 High-Value Deterministic Finance Toolkit

All financial math in FinOS is completely isolated in src/finos/tools/ and verified through property-based invariant testing (Hypothesis):

• Finance Act 2024 / FY 2024-25 (tax.py):
  • New Regime (Section 115BAC): Standard deduction increased to ₹75,000. Slabs: ₹0-3L (0%), ₹3-7L (5%), ₹7-10L (10%), ₹10-12L (15%), ₹12-15L (20%), >₹15L (30%). Section 87A rebate gives zero tax up to ₹7 Lakh taxable income.
  • Old Regime: Standard deduction ₹50,000, Section 80C (capped at ₹1.5L), Section 80D (health insurance), Section 24(b) (home loan interest up to ₹2L).
  • Budget 2024 Capital Gains: Long-Term Capital Gains (LTCG) at 12.5% on gains exceeding ₹1.25 Lakh exemption threshold. Short-Term Capital Gains (STCG) at 20%. Mandatory 4% Health and Education Cess.
• Reducing-Balance Debt Amortisation (debt.py):
  • Month-by-month principal and interest decomposition.
  • Multi-debt payoff strategies: Avalanche (highest interest rate first) vs. Snowball (lowest balance first).
  • Prepayment interest savings simulation with tenure compression.
• Date-Based Portfolio Analytics (portfolio.py):
  • Exact irregular cash flow XIRR using Newton-Raphson iteration with adaptive damping and bisection fallback.
  • Multi-year CAGR calculator with leap year tolerance.
  • Step-Up SIP Compounding projection modeling annual investment increments.

---

🔍 Hybrid RAG & Injection Defense (rag.py)

1. Multi-Format Ingestion: Ingests unstructured policy documents (.txt, .pdf) into page and chunk-level metadata.
2. Hybrid Retrieval: Blends in-memory BM25 (for exact statutory section tokens like 115BAC or 80C) with dense vector embeddings via ChromaDB.
3. Reciprocal Rank Fusion (RRF): Fuses rankings using $RRF(d) = \sum \frac{1}{60 + r(d)}$.
4. Prompt Injection Guard: Real-time regex heuristic scanner detects and purges instruction override payloads before context injection.
5. Auditable Citations: All synthesized outputs cite explicit references: [filename, Page X, Chunk Y].

---

🔒 Security & Observability

• Biometric WebAuthn / Passkeys: Passwordless FIDO2 authentication. Passkey challenges feature a 5-minute TTL and are deleted immediately upon verification to eliminate replay attacks.
• Stateless Bearer JWT: Standard HS256 tokens protect all API endpoints.
• Prometheus Metrics (GET /metrics): Native Prometheus v0.0.4 exposition reporting finos_http_requests_total, finos_http_request_duration_seconds, finos_agent_invocations_total, and finos_eval_pass_rate.
• Request Tracing: End-to-end X-Request-ID correlation middleware attached to all requests and responses.

---

💡 Why This Is Hard: Engineering Tradeoffs

1. Floating Point Roundoff in Amortisation: Financial engines use exact Decimal rounding (ROUND_HALF_UP) to prevent fractional paisa drift across 360-month loan tenures.
2. Multi-Agent State Convergence: In cyclic graphs, independent sub-agents risk overwriting state or causing infinite routing loops. FinOS enforces strict schema typing (AgentState) with fan-in barrier synchronization at the Merger node.
3. Zero-Key CI Testing: Running agentic evaluations in CI typically requires external API credentials that flake during network outages. FinOS provides a deterministic offline chat model that reproduces agent tool calling and disclaimers without outbound requests.

---

📚 Deep-Dive Documentation

• 📐 System Architecture: StateGraph topology, database models, and sequence flows.
• ⚖️ Architectural Decision Records (ADRs): Why LangGraph, why local hybrid RAG, why WebAuthn.
• 🧪 Evaluation Harness: 35 golden cases, grading rubric, and CI quality gates.
• 🛡️ Security & Threat Model: Replay attack prevention, prompt injection mitigations, and read-only boundaries.
• 🎙️ 60-Second Demo Script: Step-by-step interview walkthrough with exact prompts.
• 💼 Resume Bullets: 6 quantified bullets tailored for senior/staff engineering roles.

---

FinOS is open-source under the Apache 2.0 License.