🏦 SentiVest

🤖 AI Private Banking Agent with a Personal Financial Knowledge Graph

SentiVest is an autonomous AI banking agent built for the South African market. It goes beyond traditional banking dashboards by combining a personal financial knowledge graph with real-time transaction classification, voice-first interaction, and proactive financial intelligence.

💡 Banks give you data. SentiVest gives you understanding.

---

⚡ What Makes This Different

Traditional Banking	SentiVest
📊 Shows balance	🔮 Predicts when you'll run out
📋 Lists transactions	🛡️ Classifies and scores every one
🖥️ Static dashboard	🧬 Living knowledge graph
🚫 No memory	🧠 Remembers your goals and habits
👤 You drive	🤖 The agent drives
⏳ Reactive	⚡ Proactive

---

🏗️ Architecture

🎙️ Voice / Chat Interface        35+ handlers, multi-turn flows, persistent memory
          |
  🧠 AI Model Layer              Qwen 2.5-3B (Ollama) + rule-based fallback
          |
  🕸️ Knowledge Graph             Accounts, merchants, loans, investments, insurance, tax
          |
  🛡️ Transaction Classifier      100+ merchants, 6 fraud indicators, SAFE/FLAG/ALERT/BLOCK
          |
  ⚙️ Infrastructure              FastAPI (async) + WebSocket + Investec API (OAuth2)

---

✨ Features

🤖 Core Agent Capabilities

• 🛡️ Transaction Classification — Real-time fraud detection with weighted scoring across 100+ known merchants and 6 fraud indicators
• 🕸️ Knowledge Graph — Personal financial graph connecting accounts, merchants, categories, loans, investments, insurance, tax, budgets, goals, and patterns
• 🎙️ Voice Intelligence — 35+ voice command handlers with persistent memory, multi-turn payment flows, and natural banker-like conversation
• 💡 Proactive Insights — Budget warnings, spending habit detection, savings rate analysis, and low balance alerts without being asked

💰 Financial Tools

• 💚 Financial Health Score — 0-100 score (A-F grade) analyzing DTI, savings buffer, budget adherence, insurance coverage, investment diversity, and spending habits
• 🏦 Loan Eligibility — DTI-based assessment with verdict (Approved/Conditional/Declined), factor analysis, and max affordable calculation
• 🔄 Smart Transfer — Inter-account transfers with full audit trail in the knowledge graph
• 💳 Beneficiary Payments — Fuzzy beneficiary matching, disambiguation, multi-step confirmation flow

🎮 Life Simulator

• ⏩ Compressed real-life financial simulation (months in seconds, 0.25x-5x speed)
• 📅 Monthly cycle: Salary → Debit orders → Daily spending → Life events → Insights
• 🎲 Life events: Fraud attempts, bonuses, medical emergencies, tax refunds, salary increases, international trips, car accidents
• 📡 Real-time WebSocket event streaming with graph visualization

📱 UI

• 📱 Phone Mockup — iPhone-style card carousel, 12 pages (Home, Ledger, Chat, Budgets, Alerts, Documents, Scanner, Tasks, Report, Test, Profile)
• 🎛️ Command Center — Health score ring gauge, loan eligibility panel, AI insights feed, smart transfer, spending breakdown
• 🕸️ Knowledge Graph Visualization — D3.js interactive graph with demo step controls and simulator
• 📋 Audit Log — Real-time event feed with color-coded severity

---

🛠️ Tech Stack

Layer	Technology
⚙️ Backend	FastAPI (Python, async)
🧠 AI Model	Qwen 2.5-3B via Ollama
🕸️ Knowledge Graph	Custom in-memory graph engine
📡 Real-time	WebSocket
🏦 Banking API	Investec Open API (OAuth2)
🎙️ Voice	Web Speech API + Google STT
📊 Visualization	D3.js
🖥️ Frontend	Single-page HTML/JS/CSS

---

🚀 Quick Start

Prerequisites

• 🐍 Python 3.10+
• 🦙 Ollama (optional — falls back to rule-based responses)

Setup

# Clone
git clone https://github.com/Nevvyboi/SentiVest.git
cd SentiVest

# Virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

# Install dependencies
pip install -r requirements.txt

# (Optional) Pull AI model
ollama pull qwen2.5:3b

# Run
python main.py 8000

🌐 Open http://localhost:8000 in your browser.

🔐 Environment Variables (optional)

Create a .env file:

INVESTEC_CLIENT_ID=your_client_id
INVESTEC_CLIENT_SECRET=your_secret
INVESTEC_API_KEY=your_api_key

Without these, the app uses realistic demo data.

---

📁 Project Structure

SentiVest/
  main.py              # ⚙️  FastAPI server, 28+ API routes, WebSocket
  knowledge_graph.py   # 🕸️  Personal financial knowledge graph engine
  voice.py             # 🎙️  35+ voice command handlers, payment flows, memory
  model.py             # 🧠  AI model integration (Ollama Qwen 2.5-3B + fallback)
  agent.py             # 🛡️  Transaction classifier (100+ merchants, fraud scoring)
  simulator.py         # 🎮  Life simulator, health score, loan eligibility
  kg_routes.py         # 🔗  Knowledge graph API routes
  investec_api.py      # 🏦  Investec Open API wrapper (OAuth2)
  test_all.py          # 🧪  71+ tests
  static/
    combined.html      # 📱  Single-page app (phone + dashboard)
  presentation.html    # 🎤  Project presentation slides

📖 See individual READMEs for detailed documentation:

• static/README.md — 📱 Frontend UI documentation

---

🔌 API Overview

Endpoint	Description
POST /api/classify	🛡️ Classify transaction (SAFE/FLAG/ALERT/BLOCK)
POST /api/voice	🎙️ Process voice command
POST /api/chat	💬 AI chat with KG context
GET /api/health	💚 Financial health score (0-100)
POST /api/loan/eligibility	🏦 Loan eligibility assessment
POST /api/transfer	🔄 Smart inter-account transfer
GET /api/insights	💡 Proactive AI insights
GET /api/transactions	📋 Filtered transaction history
GET /api/budgets	📊 Budget status
GET /api/alerts	🚨 Active alerts
POST /api/simulator/start	🎮 Start life simulator
WS /ws	📡 Real-time event stream

Full API: 28+ main routes + 15+ knowledge graph routes.

---

📈 By The Numbers

Metric	Count
🔌 API Endpoints	28+ main + 15+ KG
🎙️ Voice Commands	35+
🏪 Known Merchants	100+
🧠 AI Intent Types	25+
📱 UI Pages	12
🚩 Fraud Indicators	6
🧪 Tests	71+
✨ Total Features	200+

---

🧪 Testing

python -m pytest test_all.py -v

---

🎤 Presentation

Open presentation.html in a browser for the full project presentation (20 slides, keyboard/touch navigation, presenter notes).

🎮 Controls: Space/Arrow = navigate, F = fullscreen, N = speaker notes.

---

📄 License

MIT