Spaces:
Running
Running
File size: 9,030 Bytes
021e065 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 | # 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.
|