docs/ARCHITECTURE.md

Senti AI — Architecture

Overview

Senti AI is a Kenya-focused financial intelligence platform that combines deterministic Rust computation with AI-powered language understanding. It answers financial questions, performs tax calculations, manages budgets, and provides financial advice — all in English and Swahili.

Core principle: Financial math is never delegated to the LLM. All calculations go through a deterministic Rust engine. The LLM is used only for language understanding and response formatting.

Architecture Diagram

┌─────────────┐    ┌─────────────┐    ┌─────────────────────────────┐
│  Frontend   │───▶│  FastAPI     │───▶│  Pipeline Router            │
│  (React)    │    │  Backend     │    │  (core/pipeline/router.py)  │
└─────────────┘    └─────────────┘    └──────────┬──────────────────┘
                                                  │
                          ┌───────────────────────┼───────────────────────┐
                          │                       │                       │
                    ┌─────▼─────┐          ┌──────▼──────┐         ┌─────▼─────┐
                    │  Safety    │          │  Intent     │         │  Tier     │
                    │  Check     │          │  Classify   │         │  Route    │
                    │  (empathy) │          │  (determin.)│         │  (A/B/C)  │
                    └───────────┘          └──────┬──────┘         └───────────┘
                                                  │
                    ┌─────────────────────────────┼─────────────────────────┐
                    │                             │                         │
              ┌─────▼─────┐              ┌───────▼───────┐          ┌──────▼──────┐
              │    CAG     │              │     MoE       │          │    KAG      │
              │  (context  │              │   (expert     │          │  (knowledge │
              │   packing) │              │    routing)   │          │    graph)   │
              └───────────┘              └───────┬───────┘          └─────────────┘
                                                 │
                    ┌────────────────────────────┼────────────────────────┐
                    │                            │                        │
              ┌─────▼─────┐              ┌──────▼──────┐          ┌──────▼──────┐
              │   Compute  │              │  Inference  │          │    RAG      │
              │  (Rust     │              │   Engine    │          │  (vector    │
              │   engine)  │              │  (3 levels) │          │   search)   │
              └─────┬─────┘              └──────┬──────┘          └─────────────┘
                    │                            │
                    │                    ┌───────▼───────┐
                    │                    │   LLM Layer   │
                    │                    │  (formatting) │
                    │                    └───────┬───────┘
                    │                            │
                    └────────────┬───────────────┘
                           ┌────▼────┐
                           │Validator│
                           │(output  │
                           │ check)  │
                           └────┬────┘
                                │
                           ┌────▼────┐
                           │  Audit  │
                           │  Log    │
                           └─────────┘

Module Map

core/ — Domain Logic

Module	Path	Purpose
Auth	core/auth.py	JWT authentication, password hashing
Intent Classifier	core/brain/routing/intent_classifier.py	Deterministic intent detection (rules + keywords)
MoE Router	core/brain/moe/router.py	Routes to specialist experts (Tax, Investment, Credit, Planning, Safety, Language)
CAG	core/brain/memory/cag.py	Context-Augmented Generation — warm context packing
RAG	core/brain/retrieval/rag.py	Retrieval-Augmented Generation — vector/keyword search
KAG	core/brain/knowledge_graph/	Knowledge graph reasoning (finance_kg)
Inference Engine	core/brain/inference/engine.py	3-level reasoning depth (fast/standard/deep)
Safety	core/brain/safety/empathy_interceptor.py	Crisis/distress detection with helpline referral
Output Validator	core/brain/llm/validator.py	Verifies LLM output matches Rust computation
Memory Agent	core/brain/memory/agent.py	MemGPT-inspired user memory (core + archival)
Compute Engine	core/pipeline/compute.py	Bridge to Rust senti_calc formulas
Pipeline Router	core/pipeline/router.py	Main orchestrator — the "brain"
Formula Registry	core/engines/formulas/registry.py	Single source of truth for all finance math
Scheduler	core/workflow/scheduler.py	APScheduler-based recurring jobs

backend/ — API and Infrastructure

Module	Path	Purpose
API	backend/api/main.py	FastAPI app, routes, middleware
Config	backend/config/settings.py	Environment-driven configuration
Postgres	backend/database/postgres/	SQLAlchemy models, session management
Redis	backend/database/redis/	Cache, rate limiting, sessions
Qdrant	backend/database/vector/	Vector store for RAG
Hermes	backend/api/hermes/	Payment intelligence endpoints
Institutional	backend/api/institutional/	Enterprise/tenant API

senti_calc/ — Rust Math Engine

PyO3 Rust extension for deterministic financial calculations. Compiles to a Python .pyd module. Includes:

• Kenya PAYE 2024 brackets
• Turnover Tax (TOT)
• VAT, NSSF, SHA, Housing Levy
• Loan EMI (reducing balance)
• NPV, IRR, CAGR, ROI
• Monte Carlo simulation (10,000 scenarios in <1s)
• Business valuation, working capital, breakeven

frontend/ — React UI

Vite + React + TypeScript with Tailwind CSS. Features:

• Chat-centric interface
• 3-pane institutional dashboard
• Context-aware right panel

Request Flow

1. HTTP Request → FastAPI endpoint
2. Auth → JWT validation via get_current_user
3. Safety Check → EmpathyInterceptor (crisis/distress/illegal detection)
4. Intent Classification → Deterministic rules-based classifier
5. Tier Routing → A (fast), B (standard), C (RAG-augmented)
6. CAG → Pack warm context (user profile, financial state)
7. MoE → Select specialist expert(s)
8. Compute → Dispatch to Rust engine for calculations
9. Inference → Level 1/2/3 reasoning depth
10. LLM → Format response (if USE_LM=true)
11. Validator → Check numbers match, add disclaimers
12. Audit → Log request/response to AuditLog
13. Memory → Update core memory with new facts
14. Response → Return to user

Data Flow

                    Financial Truth
                    ──────────────
User Query ──▶ Rust Engine ──▶ Numbers (deterministic)
                                    │
                                    ▼
                              LLM Formatting ──▶ Natural Language Response
                                    │
                              Validator Check ──▶ Numbers in response match Rust?

Rule: The LLM never invents financial numbers. All numbers must originate from the Rust engine.