hf/README_HF.md

metadata

title: BankBot AI
emoji: 🏦
colorFrom: blue
colorTo: green
sdk: docker
pinned: true
license: mit
short_description: >-
  AI-Native Financial Operating System — real-time streaming, fraud detection,
  forecasting

🏦 BankBot AI

AI-Native Financial Operating System

A production-grade AI fintech platform with real-time WebSocket streaming, multi-provider AI fallback, fraud detection, financial forecasting, and a premium glassmorphism UI.

---

🚀 Demo

Login with the demo account:

Email:    alex@bankbot.dev
Password: BankBot2026!

The demo account includes:

• $59,637 across 3 accounts (checking · savings · investment)
• 301 transactions across 6 months
• 1 fraud alert (Tech Store NYC, $847, 78% risk score)
• 4 financial goals (Emergency Fund · Vacation · MacBook · Down Payment)
• 4 investments (S&P 500 · AAPL · BTC · Treasury Bonds)
• 6 notifications (3 unread)

---

✨ Features

🤖 AI Financial Twin

• Contextual chat — AI knows your real balance, goals, investments, and spending patterns
• 4-tier AI fallback: OpenAI → Groq → Ollama → Rule-based (always responds)
• Real-time streaming via WebSocket — character-by-character with auto-reconnect

📊 Financial Intelligence

• Health Score — 100-point composite across 6 dimensions
• What-If Simulator — 6 sliders, instant 36-month projection
• Spending Heatmap — weekly behavioral patterns
• Category Intelligence — AI insights per spending category

🛡️ Fraud Detection

• Real-time scoring — amount spikes, timing anomalies, rapid-fire, duplicates
• Risk levels — verified / suspicious / flagged
• Live alerts — notification panel with unread count

⚡ Performance

• Dashboard: 65ms cold, 10ms cached
• Cache-aside: Redis → in-memory fallback (automatic)
• All data endpoints: < 20ms warm

🔍 Observability

• Live metrics at /api/metrics
• System Status page at /status
• Structured JSON logging with request tracing

---

🏗️ Architecture

Browser (port 7860)
    │
    ▼
Nginx (port 7860) — single entry point
    │                    │
    ▼                    ▼
Next.js (3000)      FastAPI (8000)
    │                    │
    └────────────────────┤
                         │
              ┌──────────┴──────────┐
              │                     │
         SQLite/PostgreSQL      Redis/Memory
         (auto-fallback)        (auto-fallback)
                         │
              ┌──────────┴──────────┐
              │          │          │
           OpenAI      Groq      Ollama
           (P1)        (P2)      (P3)
                              Rule-based (P4)

---

⚙️ Configuration (HF Secrets)

Set these in your Space's Settings → Repository secrets:

Secret	Required	Description
OPENAI_API_KEY	Optional*	OpenAI GPT-4o-mini
GROQ_API_KEY	Optional*	Groq llama-3.3-70b (free)
JWT_SECRET_KEY	Recommended	JWT signing secret
DATABASE_URL	Optional	External PostgreSQL (Neon/Supabase)
REDIS_URL	Optional	External Redis

*At least one AI key recommended. Without any key, the app uses rule-based responses from your actual financial data.

Get a free Groq key: https://console.groq.com/keys

---

🗄️ Database Options

Option 1: SQLite (Default — works out of the box)

No configuration needed. Data resets on Space restart (fine for demo).

Option 2: Neon PostgreSQL (Persistent)

1. Create free DB at https://neon.tech
2. Set DATABASE_URL secret: postgresql://user:pass@ep-xxx.neon.tech/bankbot?sslmode=require

Option 3: Supabase PostgreSQL (Persistent)

1. Create project at https://supabase.com
2. Set DATABASE_URL from Settings → Database → Connection string

---

📡 API Endpoints

GET  /health                    Health check
GET  /api/status                Runtime info
GET  /api/metrics               Live observability
GET  /docs                      Interactive API docs

POST /api/auth/login            Login → JWT
POST /api/auth/register         Register
GET  /api/dashboard/overview    Full dashboard (65ms)
GET  /api/transactions/         Transaction history
GET  /api/notifications/        Notifications
GET  /api/ai/coaching/score     Health score
GET  /api/ai/fraud/analysis     Fraud alerts
POST /api/ai/chat               HTTP chat
WS   /api/ai/chat/ws            Streaming chat

---

🛠️ Tech Stack

Layer	Technology
Frontend	Next.js 14, TypeScript, Tailwind CSS
Animation	Framer Motion
Charts	Recharts
State	Zustand
Backend	FastAPI, Python 3.11
Database	PostgreSQL / SQLite fallback
Cache	Redis / in-memory fallback
Auth	JWT (python-jose), bcrypt
AI	OpenAI / Groq / Ollama / Rule-based
Container	Docker (single container)
Proxy	Nginx (port 7860)

---

📁 Source Code

Full source: GitHub Repository

Documentation:

• Architecture
• API Reference
• Deployment Guide
• ER Diagram