Deploy to HF

.dockerignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+backend/venv/
+backend/.venv/
+backend/env/
+backend/*.db
+backend/.env
+
+# Node
+frontend/node_modules/
+frontend/.next/
+frontend/.env.local
+frontend/.env.production
+
+# Git
+.git/
+.github/
+
+# Docs (not needed in container)
+docs/
+.kiro/
+.vscode/
+.temporary_backup/
+
+# OS
+.DS_Store
+Thumbs.db
+*.log
+
+# Test files
+*.test.ts
+*.spec.ts
+__tests__/

.env.example

@@ -0,0 +1,54 @@
+# ============================================================
+# BankBot AI — Environment Configuration
+# ============================================================
+# Copy this file to .env and fill in your values.
+#
+# FALLBACK CHAINS (no config needed for local dev):
+#   AI:    OpenAI → Groq → Ollama → offline rule-based
+#   DB:    PostgreSQL → SQLite (auto-fallback)
+#   Cache: Redis → in-memory dict (auto-fallback)
+#
+# You only need ONE AI key for full functionality.
+# ============================================================
+
+# ─── Database ────────────────────────────────────────────────
+# Leave blank to use SQLite (great for local dev / demo)
+DATABASE_URL=postgresql://admin:adminpassword@localhost:5432/bankbot
+
+# Force SQLite regardless of DATABASE_URL
+USE_SQLITE=false
+
+# ─── Redis Cache ─────────────────────────────────────────────
+# Leave blank to use in-memory cache (auto-fallback)
+REDIS_URL=redis://localhost:6379/0
+
+# ─── AI Backends (Priority: OpenAI → Groq → Ollama → offline)
+# Priority 1: OpenAI — fastest, most capable
+# Get key: https://platform.openai.com/api-keys
+OPENAI_API_KEY=sk-your-openai-key-here
+OPENAI_MODEL=gpt-4o-mini
+
+# Priority 2: Groq — free tier, very fast inference
+# Get key: https://console.groq.com/keys
+GROQ_API_KEY=gsk_your-groq-key-here
+
+# Priority 3: Local Ollama — fully offline, no API key
+# Install: https://ollama.com → then: ollama pull llama3
+OLLAMA_MODEL=llama3:latest
+
+# ─── Authentication ───────────────────────────────────────────
+# IMPORTANT: Change this in production!
+# Generate: python -c "import secrets; print(secrets.token_hex(32))"
+JWT_SECRET_KEY=bankbot-dev-secret-change-in-production
+JWT_ALGORITHM=HS256
+ACCESS_TOKEN_EXPIRE_MINUTES=60
+
+# ─── CORS ────────────────────────────────────────────────────
+# JSON array of allowed frontend origins
+# Production example: ["https://bankbot-ai.vercel.app"]
+BACKEND_CORS_ORIGINS=["http://localhost:3000"]
+
+# ─── Frontend ────────────────────────────────────────────────
+# Backend API URL (no trailing slash)
+# Production: https://bankbot-api.onrender.com
+NEXT_PUBLIC_API_URL=http://localhost:8000

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

.github/workflows/ci.yml

@@ -0,0 +1,114 @@
+name: BankBot AI — CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  # ─── Backend ────────────────────────────────────────────────────────────────
+  backend:
+    name: Backend — Lint & Import Check
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: backend
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+
+      - name: Verify all routers import cleanly
+        env:
+          USE_SQLITE: "true"
+        run: |
+          python -c "
+          from app.main import app
+          routes = [r.path for r in app.routes if hasattr(r,'path')]
+          print(f'Routes registered: {len(routes)}')
+          assert len(routes) >= 30, f'Expected 30+ routes, got {len(routes)}'
+          print('All routers import OK')
+          "
+
+      - name: Verify demo seed script imports
+        env:
+          USE_SQLITE: "true"
+        run: python -c "import app.scripts.seed_demo; print('Seed script OK')"
+
+  # ─── Frontend ───────────────────────────────────────────────────────────────
+  frontend:
+    name: Frontend — Build & Type Check
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js 20
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci --legacy-peer-deps
+
+      - name: Type check
+        run: npx tsc --noEmit
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Production build
+        env:
+          NEXT_PUBLIC_API_URL: http://localhost:8000
+        run: npm run build
+
+      - name: Verify build output
+        run: |
+          test -d .next/standalone && echo "Standalone build OK" || echo "No standalone (OK for non-Docker)"
+          test -d .next/static && echo "Static assets OK"
+
+  # ─── Docker ─────────────────────────────────────────────────────────────────
+  docker:
+    name: Docker — Build Check
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build backend image
+        run: docker build -t bankbot-backend:ci ./backend
+
+      - name: Build frontend image
+        run: |
+          docker build \
+            --build-arg NEXT_PUBLIC_API_URL=http://localhost:8000 \
+            -t bankbot-frontend:ci \
+            ./frontend
+
+      - name: Smoke test backend container
+        run: |
+          docker run -d --name backend-test \
+            -e USE_SQLITE=true \
+            -e JWT_SECRET_KEY=ci-test-secret \
+            -p 8000:8000 \
+            bankbot-backend:ci
+          sleep 10
+          curl -f http://localhost:8000/health || exit 1
+          curl -f http://localhost:8000/api/status || exit 1
+          echo "Backend smoke test passed"
+          docker stop backend-test

.gitignore

@@ -0,0 +1,29 @@
+__pycache__/
+*.pyc
+.streamlit/
+session.json
+chat_history.json
+users.json
+BankBot_Accuracy_Document.docx
+generate_accuracy.py
+src/
+.env
+.env.local
+.env.production
+.venv
+venv/
+env/
+
+# Next.js
+frontend/.next/
+frontend/node_modules/
+frontend/out/
+
+# Local OCR Windows Binaries (Version Agnostic)
+poppler-*/
+poppler.zip
+tesseract-setup.exe
+tesseract-ocr/
+*.exe
+*.zip
+*.db

.kiro/specs/bankbot-ai-intelligence/.config.kiro

@@ -0,0 +1 @@
+{"specId": "bdc55ba3-7595-4d07-b12c-ac91a1297320", "workflowType": "design-first", "specType": "feature"}

.kiro/specs/bankbot-ai-intelligence/design.md

@@ -0,0 +1,1393 @@
+# Design Document: BankBot AI Intelligence & API (Phase 4)
+
+## Overview
+
+Phase 4 delivers the complete AI intelligence layer for BankBot — a FastAPI-based backend that
+exposes financial forecasting, behavioral analytics, coaching, fraud detection, simulation, and
+real-time WebSocket chat. The system is built for resilience: it auto-detects and falls back
+across OpenAI → Groq → local Ollama for AI, PostgreSQL → SQLite for persistence, and
+Redis → in-memory TTL cache for caching, so the application runs immediately in any environment.
+
+The AI layer is already partially implemented. This design documents the full intended architecture,
+the contracts between modules, the formal specifications for key algorithms, and the integration
+points that must be verified or completed.
+
+---
+
+## Architecture
+
+```mermaid
+graph TD
+    FE["Next.js Frontend\n(port 3000)"]
+    GW["FastAPI Gateway\n(main.py — port 8000)"]
+    AIR["ai/router.py\n(HTTP endpoints)"]
+    WSR["websocket/router.py\n(WS endpoint)"]
+    CM["websocket/connection_manager.py"]
+
+    subgraph AI_Engines["AI Engine Modules (backend/app/ai/)"]
+        FC["forecasting.py"]
+        SIM["simulation.py"]
+        BEH["behavior.py"]
+        COA["coaching.py"]
+        SUB["subscriptions.py"]
+        FRD["fraud.py"]
+        CHT["chat.py"]
+        OLL["ollama_integration.py"]
+    end
+
+    subgraph Infra["Infrastructure Layer"]
+        DB["database/database.py\n(PostgreSQL → SQLite fallback)"]
+        MDL["database/models.py\n(SQLAlchemy ORM)"]
+        CAC["middleware/cache.py\n(Redis → MemoryCache fallback)"]
+    end
+
+    subgraph AI_Backends["External AI Backends"]
+        OAI["OpenAI API\n(gpt-4o-mini)"]
+        GRQ["Groq API\n(llama-3.3-70b)"]
+        LOC["Local Ollama\n(llama3:latest)"]
+    end
+
+    FE -->|"REST /api/ai/*"| GW
+    FE -->|"WS /api/ai/chat/ws"| GW
+    GW --> AIR
+    GW --> WSR
+    WSR --> CM
+    AIR --> FC & SIM & BEH & COA & SUB & FRD & CHT
+    WSR --> CHT
+    CHT --> OLL
+    COA --> OLL
+    OLL -->|"priority 1"| OAI
+    OLL -->|"priority 2"| GRQ
+    OLL -->|"priority 3"| LOC
+    AIR --> CAC
+    FC & SIM & BEH & COA & SUB & FRD & CHT --> DB
+    DB --> MDL
+```
+
+---
+
+## Sequence Diagrams
+
+### HTTP AI Endpoint Request Flow
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant R as ai/router.py
+    participant CAC as cache.py
+    participant ENG as AI Engine Module
+    participant DB as database.py
+    participant LLM as AI Backend (OpenAI/Groq/Ollama)
+
+    C->>R: GET /api/ai/twin/predict?user_id=X
+    R->>CAC: cache.get("ai:twin:predict:X")
+    alt Cache Hit
+        CAC-->>R: cached JSON
+        R-->>C: 200 OK (cached)
+    else Cache Miss
+        R->>ENG: predict_future_balance(db, user_id)
+        ENG->>DB: query Account, Transaction
+        DB-->>ENG: ORM objects
+        ENG-->>R: result dict
+        R->>CAC: cache.set(key, result, ttl=300)
+        R-->>C: 200 OK (fresh)
+    end
+```
+
+### WebSocket Streaming Chat Flow
+
+```mermaid
+sequenceDiagram
+    participant C as Browser Client
+    participant WS as websocket/router.py
+    participant CM as connection_manager.py
+    participant CHT as chat.py
+    participant LLM as AI Backend
+
+    C->>WS: WS connect /api/ai/chat/ws?user_id=X
+    WS->>CM: ws_manager.connect(websocket, user_id)
+    CM-->>WS: accepted
+    C->>WS: send JSON {"type":"chat","message":"..."}
+    WS->>CHT: stream_chat_response(db, user_id, prompt)
+    CHT->>LLM: streaming completion request
+    loop For each token chunk
+        LLM-->>CHT: token
+        CHT-->>WS: yield chunk
+        WS-->>C: send_json {"type":"chat_chunk","content":"..."}
+    end
+    WS-->>C: send_json {"type":"chat_end"}
+```
+
+### AI Backend Fallback Chain
+
+```mermaid
+sequenceDiagram
+    participant M as Module (chat/coaching)
+    participant OLL as ollama_integration.py
+    participant OAI as OpenAI API
+    participant GRQ as Groq API
+    participant LOC as Local Ollama
+
+    M->>OLL: get_ai_response(prompt)
+    alt OPENAI_API_KEY set
+        OLL->>OAI: chat.completions.create(gpt-4o-mini)
+        OAI-->>OLL: response
+    else GROQ_API_KEY set
+        OLL->>GRQ: client.chat.completions.create
+        GRQ-->>OLL: response
+    else Ollama reachable
+        OLL->>LOC: POST /api/chat (llama3:latest)
+        LOC-->>OLL: response
+    else All backends down
+        OLL-->>M: None
+        M->>M: get_offline_chat_fallback()
+    end
+    OLL-->>M: response string
+```
+
+---
+
+## Components and Interfaces
+
+### Component 1: database/database.py — Resilient DB Engine
+
+**Purpose**: Provides a SQLAlchemy engine and session factory with automatic PostgreSQL → SQLite fallback.
+
+**Interface**:
+```python
+engine: Engine                    # SQLAlchemy engine (PostgreSQL or SQLite)
+SessionLocal: sessionmaker        # Session factory
+Base: DeclarativeMeta             # ORM base class
+
+def get_db() -> Generator[Session, None, None]:
+    """FastAPI dependency — yields a DB session, closes on exit."""
+```
+
+**Responsibilities**:
+- Read `DATABASE_URL` from env; attempt PostgreSQL connection
+- On `OperationalError`, switch to `sqlite:///./bankbot.db` with `check_same_thread=False`
+- Expose `get_db()` as a FastAPI `Depends` injectable
+
+---
+
+### Component 2: middleware/cache.py — Resilient Cache
+
+**Purpose**: Provides a unified `get/set/delete` cache interface backed by Redis or an in-memory TTL dict.
+
+**Interface**:
+```python
+class MemoryCache:
+    def get(self, key: str) -> Any | None
+    def set(self, key: str, value: Any, ttl: int | None = None) -> None
+    def delete(self, key: str) -> None
+
+class CacheManager:
+    def get(self, key: str) -> Any | None
+    def set(self, key: str, value: Any, ttl: int | None = None) -> None
+    def delete(self, key: str) -> None
+
+cache: CacheManager   # module-level singleton
+```
+
+**Responsibilities**:
+- On startup, attempt `redis.Redis.from_url(...).ping()`
+- On failure, fall back to `MemoryCache` (thread-safe via `threading.Lock`)
+- Serialize/deserialize values as JSON when using Redis
+
+---
+
+### Component 3: ai/forecasting.py — Financial Twin Engine
+
+**Purpose**: Computes balance projections, savings/investment growth curves, and scenario comparisons.
+
+**Interface**:
+```python
+def get_cashflow_metrics(db: Session, user_id: str, days: int = 90
+    ) -> tuple[float, float, float]:
+    """Returns (current_balance, avg_daily_income, avg_daily_spending)."""
+
+def predict_future_balance(db: Session, user_id: str, projection_days: int = 90
+    ) -> dict:
+    """Returns chart-ready balance projection for 30/60/90 days."""
+
+def forecast_savings_and_investments(db: Session, user_id: str, projection_months: int = 12
+    ) -> dict:
+    """Returns monthly savings growth, investment growth, and debt decline curves."""
+
+def simulate_future_scenarios(db: Session, user_id: str, projection_months: int = 6
+    ) -> dict:
+    """Returns three scenario trajectories: status_quo, frugal, lifestyle_inflation."""
+```
+
+---
+
+### Component 4: ai/simulation.py — What-If Simulator
+
+**Purpose**: Evaluates the financial impact of hypothetical purchases, investment changes, and subscription cancellations.
+
+**Interface**:
+```python
+def simulate_purchase_impact(
+    db: Session, user_id: str, amount: float, category: str, merchant: str
+) -> dict:
+    """Returns risk_level, projected_balance, emergency_buffer_breached, recommendation."""
+
+def simulate_investment_impact(
+    db: Session, user_id: str, monthly_sip: float, asset_type: str, lump_sum: float = 0.0
+) -> dict:
+    """Returns 1/3/5-year growth projection, affordability check, risk_level."""
+
+def simulate_subscription_cancellation(
+    db: Session, user_id: str, subscription_ids: list[str]
+) -> dict:
+    """Returns monthly/yearly savings, goal impact, and recommendation."""
+```
+
+---
+
+### Component 5: ai/behavior.py — Behavioral Analytics Engine
+
+**Purpose**: Detects spending patterns (late-night, weekend spikes, dopamine/stress triggers) from transaction history.
+
+**Interface**:
+```python
+def analyze_spending_behavior(db: Session, user_id: str, days: int = 90) -> dict:
+    """
+    Returns:
+      insights: list[str]       — human-readable behavioral findings
+      metrics: dict             — late_night_count, weekend_pct, impulsive_count, etc.
+      category_breakdown: dict  — spending totals per category
+    """
+```
+
+---
+
+### Component 6: ai/coaching.py — Financial Health Coach
+
+**Purpose**: Computes a multi-dimensional Financial Health Score and generates LLM-grounded daily briefings.
+
+**Interface**:
+```python
+def calculate_financial_health_score(db: Session, user_id: str) -> dict:
+    """
+    Returns overall_score (0-100), per-category sub-scores, LLM explanation,
+    and actionable_improvements list.
+    """
+
+def generate_daily_briefing(db: Session, user_id: str) -> dict:
+    """
+    Returns date, user_name, LLM-generated briefing text, and key metrics dict.
+    """
+```
+
+---
+
+### Component 7: ai/subscriptions.py — Subscription Optimizer
+
+**Purpose**: Detects duplicate, unused, and cancellable subscriptions from the `subscriptions` table.
+
+**Interface**:
+```python
+def analyze_subscriptions(db: Session, user_id: str) -> dict:
+    """
+    Returns subscriptions list, duplicates list, unused_subscriptions list,
+    yearly_savings_potential, and risk_analysis per merchant.
+    """
+```
+
+---
+
+### Component 8: ai/fraud.py — Fraud & Anomaly Detector
+
+**Purpose**: Scores individual transactions for fraud risk using rule-based heuristics and logs alerts.
+
+**Interface**:
+```python
+def evaluate_transaction_for_fraud(db: Session, transaction_id: str) -> dict:
+    """
+    Returns fraud_risk_score (0-100), is_anomalous, explanations list, status string.
+    Writes FraudLog to DB if score >= 30.
+    """
+
+def get_user_fraud_alerts(db: Session, user_id: str) -> dict:
+    """Returns total_alerts, pending_reviews count, and full alerts list."""
+```
+
+---
+
+### Component 9: ai/chat.py — Contextual Chat Agent
+
+**Purpose**: Provides HTTP and streaming chat responses grounded in the user's live financial profile, with session memory.
+
+**Interface**:
+```python
+class ChatMemoryManager:
+    def get_history(self, user_id: str) -> list[dict]
+    def add_message(self, user_id: str, role: str, content: str) -> None
+    def clear_history(self, user_id: str) -> None
+
+def build_user_context_string(db: Session, user_id: str) -> str:
+    """Assembles a financial profile string from DB for the system prompt."""
+
+def get_contextual_system_prompt(db: Session, user_id: str) -> str:
+    """Returns the full system prompt with embedded financial context."""
+
+def get_chat_response(db: Session, user_id: str, prompt: str) -> str:
+    """Synchronous HTTP chat — tries OpenAI → Groq → Ollama → offline fallback."""
+
+def stream_chat_response(db: Session, user_id: str, prompt: str) -> Generator[str, None, None]:
+    """Streaming generator — yields token chunks for WebSocket delivery."""
+```
+
+---
+
+### Component 10: ai/ollama_integration.py — AI Backend Abstraction
+
+**Purpose**: Abstracts OpenAI, Groq, and local Ollama behind a unified interface; detects available backends at startup.
+
+**Interface**:
+```python
+def has_active_ai_backend() -> bool
+def get_ai_response(prompt: str, history: list | None, language: str) -> str | None
+def stream_ai_response(prompt: str, history: list | None, language: str) -> Generator[str, None, None]
+def get_groq_response(prompt, history, model, language) -> str | None
+def stream_groq_response(prompt, history, model, language) -> Generator[str, None, None]
+def get_ollama_response(prompt, history, model, language) -> str | None
+def stream_ollama_response(prompt, history, model, language) -> Generator[str, None, None]
+```
+
+---
+
+### Component 11: websocket/connection_manager.py — WebSocket Registry
+
+**Purpose**: Maintains a per-user registry of active WebSocket connections; supports targeted and broadcast messaging.
+
+**Interface**:
+```python
+class WebSocketConnectionManager:
+    async def connect(self, websocket: WebSocket, user_id: str) -> None
+    def disconnect(self, websocket: WebSocket, user_id: str) -> None
+    async def send_personal_message(self, message: dict, user_id: str) -> None
+    async def broadcast(self, message: dict) -> None
+
+ws_manager: WebSocketConnectionManager   # module-level singleton
+```
+
+---
+
+### Component 12: ai/router.py — HTTP API Router
+
+**Purpose**: Mounts all `/api/ai/*` HTTP endpoints, applies cache-aside pattern, and delegates to engine modules.
+
+**Endpoints**:
+
+| Method | Path | Engine Function | Cache TTL |
+|--------|------|-----------------|-----------|
+| GET | `/api/ai/twin/predict` | `predict_future_balance` | 300s |
+| GET | `/api/ai/twin/future` | `forecast_savings_and_investments` | 300s |
+| GET | `/api/ai/twin/scenarios` | `simulate_future_scenarios` | 300s |
+| POST | `/api/ai/simulate/purchase` | `simulate_purchase_impact` | none |
+| POST | `/api/ai/simulate/investment` | `simulate_investment_impact` | none |
+| POST | `/api/ai/simulate/subscription` | `simulate_subscription_cancellation` | none |
+| GET | `/api/ai/behavior/insights` | `analyze_spending_behavior` | 600s |
+| GET | `/api/ai/coaching/briefing` | `generate_daily_briefing` | 3600s |
+| GET | `/api/ai/coaching/score` | `calculate_financial_health_score` | 600s |
+| GET | `/api/ai/subscriptions/optimize` | `analyze_subscriptions` | 600s |
+| GET | `/api/ai/fraud/analysis` | `get_user_fraud_alerts` | none |
+| POST | `/api/ai/fraud/evaluate/{id}` | `evaluate_transaction_for_fraud` | none |
+| POST | `/api/ai/chat` | `get_chat_response` | none |
+
+---
+
+### Component 13: websocket/router.py — WebSocket Endpoint
+
+**Purpose**: Handles the `/api/ai/chat/ws` WebSocket lifecycle, dispatches message types, and streams AI replies.
+
+**Message Protocol**:
+
+| Direction | JSON Shape | Meaning |
+|-----------|-----------|---------|
+| Client → Server | `{"type":"chat","message":"..."}` | Send a chat prompt |
+| Client → Server | `{"type":"ping"}` | Keepalive |
+| Server → Client | `{"type":"chat_start"}` | AI generation beginning |
+| Server → Client | `{"type":"chat_chunk","content":"..."}` | Streaming token |
+| Server → Client | `{"type":"chat_end"}` | Generation complete |
+| Server → Client | `{"type":"pong"}` | Keepalive reply |
+| Server → Client | `{"type":"error","message":"..."}` | Error notification |
+
+---
+
+## Data Models
+
+### Core ORM Models (database/models.py)
+
+```python
+class User(Base):
+    id: str (UUID PK)
+    email: str (unique)
+    password_hash: str
+    profile_data: JSON          # {"name": str, "phone": str}
+    financial_personality: str  # "Saver" | "Investor" | "Impulsive Spender" | ...
+    ai_personalization_settings: JSON
+    created_at: DateTime
+    # relationships: accounts, subscriptions, goals, investments, ai_insights, notifications
+
+class Account(Base):
+    id: str (UUID PK)
+    user_id: str (FK → users.id)
+    type: str                   # "checking" | "savings"
+    balance: float
+    currency: str               # default "USD"
+    status: str                 # "active" | "inactive"
+    # relationships: transactions
+
+class Transaction(Base):
+    id: str (UUID PK)
+    account_id: str (FK → accounts.id)
+    amount: float
+    type: str                   # "credit" | "debit"
+    category: str               # "Food" | "Shopping" | "Income" | ...
+    timestamp: DateTime
+    merchant: str
+    tags: JSON                  # list[str]
+    ai_generated_metadata: JSON # {"is_recurring": bool, "confidence": float}
+    spending_emotion_label: str # "happy" | "regret" | "neutral" | "essential"
+
+class Subscription(Base):
+    id: str (UUID PK)
+    user_id: str (FK → users.id)
+    merchant: str
+    amount: float
+    billing_cycle: str          # "monthly" | "yearly"
+    active: bool
+    ai_usage_detection: JSON    # {"usage_frequency": "high"|"medium"|"low"|"none"}
+
+class Goal(Base):
+    id: str (UUID PK)
+    user_id: str (FK → users.id)
+    title: str
+    target_amount: float
+    current_amount: float
+    target_date: DateTime
+    ai_generated_plan: JSON     # {"monthly_saving_required": float, "risk": str}
+
+class Investment(Base):
+    id: str (UUID PK)
+    user_id: str (FK → users.id)
+    asset_name: str
+    type: str                   # "stock" | "crypto" | "mutual_fund" | "fd" | "bond"
+    amount_invested: float
+    current_value: float
+    portfolio_allocation: float # percentage
+    ai_risk_analysis: JSON      # {"risk_level": str, "recommendation": str}
+
+class FraudLog(Base):
+    id: str (UUID PK)
+    transaction_id: str (FK → transactions.id, unique)
+    risk_score: float           # 0.0 – 1.0
+    suspicious_activity_details: str
+    status: str                 # "pending" | "resolved" | "false_positive"
+```
+
+### API Response Schemas (Pydantic — ai/router.py)
+
+```python
+class PurchaseRequest(BaseModel):
+    amount: float
+    merchant: str
+    category: str
+
+class InvestmentRequest(BaseModel):
+    monthly_sip: float
+    asset_type: str             # "stock" | "crypto" | "mutual_fund" | "fd" | "bond"
+    lump_sum: float = 0.0
+
+class SubscriptionSimulationRequest(BaseModel):
+    subscription_ids: list[str]
+
+class ChatMessageRequest(BaseModel):
+    message: str
+```
+
+---
+
+## Algorithmic Pseudocode
+
+### Algorithm 1: Balance Projection (predict_future_balance)
+
+```pascal
+ALGORITHM predict_future_balance(db, user_id, projection_days=90)
+INPUT:  db — SQLAlchemy Session
+        user_id — string UUID
+        projection_days — integer in [1, 365]
+OUTPUT: result — dict with chart_data, projected_balance, insight
+
+BEGIN
+  // Step 1: Gather cashflow metrics
+  (current_balance, daily_income, daily_spending) ← get_cashflow_metrics(db, user_id, days=90)
+
+  // Step 2: Compute net daily cashflow
+  net_daily ← daily_income - daily_spending
+
+  // Step 3: Project terminal balance
+  projected_balance ← MAX(0.0, current_balance + net_daily * projection_days)
+
+  // Step 4: Compute percentage change
+  IF current_balance > 0 THEN
+    percent_change ← (projected_balance - current_balance) / current_balance * 100
+  ELSE
+    percent_change ← 0.0
+  END IF
+
+  // Step 5: Build chart data (every 5 days)
+  chart_data ← []
+  FOR day ← 0 TO projection_days STEP 5 DO
+    ASSERT day >= 0 AND day <= projection_days
+    val ← MAX(0.0, current_balance + net_daily * day)
+    chart_data.APPEND({date: now() + day_offset(day), balance: ROUND(val, 2)})
+  END FOR
+
+  ASSERT LENGTH(chart_data) >= 1
+  ASSERT chart_data[0].balance = ROUND(current_balance, 2)
+
+  RETURN {current_balance, projected_balance, percent_change, net_daily, insight, chart_data}
+END
+```
+
+**Preconditions:**
+- `user_id` references an existing user with at least one account
+- `projection_days` is a positive integer
+
+**Postconditions:**
+- `projected_balance >= 0.0` (floored at zero, no negative balances)
+- `chart_data[0].balance == current_balance` (first point is always current state)
+- `len(chart_data) == ceil(projection_days / 5) + 1`
+
+**Loop Invariant:** For each iteration, `day` is a non-negative multiple of 5 and `val >= 0.0`
+
+---
+
+### Algorithm 2: Financial Health Score (calculate_financial_health_score)
+
+```pascal
+ALGORITHM calculate_financial_health_score(db, user_id)
+INPUT:  db — SQLAlchemy Session
+        user_id — string UUID
+OUTPUT: result — dict with overall_score (0-100), categories, explanation, improvements
+
+BEGIN
+  // Gather raw data
+  accounts ← db.query(Account).filter(user_id)
+  total_balance ← SUM(acc.balance FOR acc IN accounts)
+  savings_balance ← SUM(acc.balance FOR acc IN accounts WHERE acc.type = "savings")
+  (_, daily_income, daily_spending) ← get_cashflow_metrics(db, user_id)
+  monthly_income ← MAX(1000.0, daily_income * 30.4)
+  monthly_spending ← daily_spending * 30.4
+
+  // Sub-score 1: Savings Consistency (max 20)
+  goal_savings ← SUM(g.current_amount FOR g IN goals)
+  IF goal_savings > 1000 THEN savings_score ← 20
+  ELSE IF goal_savings > 0 THEN savings_score ← 15
+  ELSE savings_score ← 10
+  END IF
+
+  // Sub-score 2: Debt Ratio (max 20)
+  debt_goals ← SUM(g.target - g.current FOR g IN goals WHERE "debt" IN g.title)
+  debt_to_income ← (debt_goals * 0.05) / monthly_income
+  IF debt_to_income > 0.40 THEN debt_score ← 5
+  ELSE IF debt_to_income > 0.20 THEN debt_score ← 12
+  ELSE IF debt_to_income > 0.05 THEN debt_score ← 18
+  ELSE debt_score ← 20
+  END IF
+
+  // Sub-score 3: Spending Discipline (max 20)
+  savings_rate ← (monthly_income - monthly_spending) / monthly_income
+  IF savings_rate >= 0.30 THEN discipline_score ← 20
+  ELSE IF savings_rate >= 0.15 THEN discipline_score ← 16
+  ELSE IF savings_rate >= 0.0 THEN discipline_score ← 12
+  ELSE discipline_score ← 5
+  END IF
+
+  // Sub-score 4: Emergency Fund (max 20)
+  months_buffer ← savings_balance / MAX(500.0, monthly_spending)
+  IF months_buffer >= 6.0 THEN emergency_score ← 20
+  ELSE IF months_buffer >= 3.0 THEN emergency_score ← 15
+  ELSE IF months_buffer >= 1.0 THEN emergency_score ← 8
+  ELSE emergency_score ← 0
+  END IF
+
+  // Sub-score 5: Investment Index (max 10)
+  inv_total ← SUM(i.current_value FOR i IN investments)
+  IF inv_total > 5000 THEN investment_score ← 10
+  ELSE IF inv_total > 0 THEN investment_score ← 6
+  ELSE investment_score ← 0
+  END IF
+
+  // Sub-score 6: Subscription Efficiency (max 10)
+  sub_cost ← SUM(monthly_cost(s) FOR s IN active_subscriptions)
+  sub_ratio ← sub_cost / monthly_income
+  IF sub_ratio > 0.10 THEN sub_score ← 3
+  ELSE IF sub_ratio > 0.05 THEN sub_score ← 7
+  ELSE sub_score ← 10
+  END IF
+
+  // Aggregate
+  overall_score ← CLAMP(savings_score + debt_score + discipline_score +
+                         emergency_score + investment_score + sub_score, 0, 100)
+
+  ASSERT overall_score >= 0 AND overall_score <= 100
+  ASSERT savings_score + debt_score + discipline_score + emergency_score +
+         investment_score + sub_score = overall_score (before clamping)
+
+  RETURN {overall_score, categories, explanation (LLM or fallback), improvements}
+END
+```
+
+**Preconditions:**
+- `monthly_income` is floored at 1000.0 to prevent division-by-zero
+- `monthly_spending` is floored at 500.0 for emergency fund calculation
+
+**Postconditions:**
+- `0 <= overall_score <= 100`
+- All six sub-scores are non-negative and within their declared maximums
+- `improvements` is non-empty (at least one suggestion or "maintain habits" message)
+
+---
+
+### Algorithm 3: Fraud Risk Scoring (evaluate_transaction_for_fraud)
+
+```pascal
+ALGORITHM evaluate_transaction_for_fraud(db, transaction_id)
+INPUT:  db — SQLAlchemy Session
+        transaction_id — string UUID
+OUTPUT: result — dict with fraud_risk_score, is_anomalous, explanations, status
+
+BEGIN
+  txn ← db.query(Transaction).filter(id = transaction_id).first()
+  IF txn IS NULL THEN RETURN {error: "Transaction not found"} END IF
+
+  account ← db.query(Account).filter(id = txn.account_id).first()
+  history ← last 30 debit transactions for account.user_id (excluding txn)
+
+  score ← 0
+  reasons ← []
+
+  // Rule 1: Amount spike detection
+  IF history IS NOT EMPTY THEN
+    avg_amount ← MEAN(h.amount FOR h IN history)
+    std_amount ← STDDEV(h.amount FOR h IN history)
+    IF txn.amount > avg_amount * 3.5 THEN
+      score ← score + 40
+      reasons.APPEND("Amount is 3.5x historical average")
+    ELSE IF txn.amount > avg_amount * 2.0 THEN
+      score ← score + 20
+      reasons.APPEND("Amount is 2x historical average")
+    END IF
+  END IF
+
+  // Rule 2: Late-night timing (11PM – 4AM)
+  hour ← txn.timestamp.hour
+  IF hour >= 23 OR hour < 4 THEN
+    score ← score + 25
+    reasons.APPEND("Unusual timing: 11PM–4AM")
+  END IF
+
+  // Rule 3: High-frequency (< 3 minutes since last transaction)
+  IF history IS NOT EMPTY THEN
+    time_diff ← ABS(txn.timestamp - history[0].timestamp).seconds
+    IF time_diff < 180 THEN
+      score ← score + 20
+      reasons.APPEND("Multiple transactions within 3 minutes")
+    END IF
+  END IF
+
+  // Rule 4: Duplicate detection (same merchant + amount within 10 minutes)
+  FOR prev IN history[0..4] DO
+    time_diff ← ABS(txn.timestamp - prev.timestamp).seconds
+    IF prev.merchant = txn.merchant AND prev.amount = txn.amount AND time_diff < 600 THEN
+      score ← score + 30
+      reasons.APPEND("Potential duplicate payment")
+      BREAK
+    END IF
+  END FOR
+
+  score ← MIN(100, score)
+
+  // Persist if above threshold
+  IF score >= 30 AND NOT EXISTS FraudLog(transaction_id) THEN
+    db.INSERT FraudLog(transaction_id, risk_score=score/100, details=reasons, status="pending")
+    db.COMMIT()
+  END IF
+
+  status ← IF score >= 50 THEN "flagged"
+            ELSE IF score >= 30 THEN "suspicious"
+            ELSE "verified"
+
+  ASSERT score >= 0 AND score <= 100
+  RETURN {transaction_id, fraud_risk_score: score, is_anomalous: score >= 30, explanations: reasons, status}
+END
+```
+
+**Preconditions:**
+- `transaction_id` must reference an existing transaction with a valid account
+- History window is capped at 30 transactions to bound computation
+
+**Postconditions:**
+- `0 <= fraud_risk_score <= 100`
+- A `FraudLog` row is created if and only if `score >= 30` and no prior log exists
+- `status` is exactly one of `"flagged"`, `"suspicious"`, or `"verified"`
+
+**Loop Invariant (duplicate check):** At each iteration, all previously checked transactions were not duplicates
+
+---
+
+### Algorithm 4: Behavioral Pattern Detection (analyze_spending_behavior)
+
+```pascal
+ALGORITHM analyze_spending_behavior(db, user_id, days=90)
+INPUT:  db — SQLAlchemy Session
+        user_id — string UUID
+        days — lookback window in days
+OUTPUT: result — dict with insights, metrics, category_breakdown
+
+BEGIN
+  account_ids ← [acc.id FOR acc IN accounts WHERE user_id]
+  txns ← debit transactions in last `days` days for account_ids
+
+  IF txns IS EMPTY THEN RETURN default_empty_result END IF
+
+  amounts ← [t.amount FOR t IN txns]
+  avg_txn ← MEAN(amounts)
+  std_txn ← STDDEV(amounts)
+
+  // Classify each transaction
+  FOR t IN txns DO
+    hour ← t.timestamp.hour
+    day_of_week ← t.timestamp.weekday()
+
+    IF hour >= 23 OR hour < 4 THEN late_night_txns.ADD(t) END IF
+    IF day_of_week IN {4, 5, 6} THEN weekend_txns.ADD(t) END IF
+
+    IF t.amount > (avg_txn + 1.5 * std_txn) AND t.category IN {"Shopping","Entertainment","Food"} THEN
+      impulsive_txns.ADD(t)
+    END IF
+
+    emotion ← LOWER(t.spending_emotion_label OR "")
+    IF emotion = "regret" THEN stress_txns.ADD(t)
+    ELSE IF emotion IN {"happy","dopamine"} OR (t.category = "Shopping" AND t.amount > avg_txn) THEN
+      dopamine_txns.ADD(t)
+    END IF
+
+    category_totals[t.category OR "Other"] += t.amount
+  END FOR
+
+  // Generate insights
+  insights ← []
+  late_night_pct ← len(late_night_txns) / len(txns) * 100
+  IF late_night_pct > 15 THEN insights.ADD(late_night_warning) END IF
+
+  weekend_pct ← len(weekend_txns) / len(txns) * 100
+  IF weekend_pct > 45 AND weekend_avg > weekday_avg * 1.2 THEN
+    insights.ADD(weekend_spike_warning)
+  END IF
+
+  IF len(dopamine_txns) > 3 THEN insights.ADD(dopamine_warning) END IF
+  IF len(stress_txns) > 0 THEN insights.ADD(stress_warning) END IF
+  IF insights IS EMPTY THEN insights.ADD(stable_spending_message) END IF
+
+  ASSERT len(insights) >= 1
+  RETURN {insights, metrics, category_breakdown}
+END
+```
+
+**Preconditions:**
+- Only `debit` transactions are analyzed (income credits are excluded)
+- `std_txn` defaults to 0.0 when fewer than 2 transactions exist
+
+**Postconditions:**
+- `insights` always contains at least one entry
+- `metrics.weekend_pct` is in range `[0.0, 100.0]`
+- `category_breakdown` values are non-negative floats
+
+---
+
+### Algorithm 5: Cache-Aside Pattern (ai/router.py)
+
+```pascal
+ALGORITHM cache_aside_get(cache_key, ttl, compute_fn, db, user_id)
+INPUT:  cache_key — string
+        ttl — integer seconds
+        compute_fn — function(db, user_id) → dict
+        db — Session
+        user_id — string
+OUTPUT: result — dict (from cache or freshly computed)
+
+BEGIN
+  cached ← cache.get(cache_key)
+  IF cached IS NOT NULL THEN
+    RETURN cached
+  END IF
+
+  result ← compute_fn(db, user_id)
+  cache.set(cache_key, result, ttl=ttl)
+  RETURN result
+END
+```
+
+**Preconditions:**
+- `compute_fn` is a pure function with no side effects on the DB
+- `ttl > 0`
+
+**Postconditions:**
+- Returned value is semantically equivalent whether served from cache or computed fresh
+- Cache is populated after a miss so the next call within TTL is served from cache
+
+---
+
+### Algorithm 6: Compound Growth Projection (forecast_savings_and_investments)
+
+```pascal
+ALGORITHM forecast_savings_and_investments(db, user_id, projection_months=12)
+INPUT:  db — Session, user_id — string, projection_months — int
+OUTPUT: dict with savings_growth, investment_growth, debt_decline arrays
+
+BEGIN
+  savings_apr ← 0.04   // 4% APY
+  investment_apr ← 0.08 // 8% APY
+
+  (_, daily_income, daily_spending) ← get_cashflow_metrics(db, user_id)
+  net_monthly ← MAX(0.0, (daily_income - daily_spending) * 30.4)
+  monthly_savings_addition ← net_monthly * 0.5
+  monthly_investment_addition ← net_monthly * 0.3
+  monthly_debt_payment ← MAX(150.0, net_monthly * 0.1)
+
+  current_savings ← savings_balance
+  current_inv ← total_invested
+  total_debt ← debt_from_goals OR 5000.0
+
+  FOR month ← 0 TO projection_months DO
+    IF month > 0 THEN
+      // Compound interest with monthly additions
+      current_savings ← (current_savings + monthly_savings_addition) * (1 + savings_apr / 12)
+      current_inv ← (current_inv + monthly_investment_addition) * (1 + investment_apr / 12)
+      total_debt ← MAX(0.0, total_debt - monthly_debt_payment)
+    END IF
+
+    ASSERT current_savings >= 0.0
+    ASSERT current_inv >= 0.0
+    ASSERT total_debt >= 0.0
+
+    savings_data.APPEND({month: "Month N", amount: ROUND(current_savings, 2)})
+    investment_data.APPEND({month: "Month N", amount: ROUND(current_inv, 2)})
+    debt_data.APPEND({month: "Month N", amount: ROUND(total_debt, 2)})
+  END FOR
+
+  RETURN {savings_growth, investment_growth, debt_decline, ...summary_fields}
+END
+```
+
+**Loop Invariant:** At each iteration, `current_savings >= 0`, `current_inv >= 0`, `total_debt >= 0`
+
+**Postconditions:**
+- All three arrays have exactly `projection_months + 1` entries
+- `debt_decline` is monotonically non-increasing
+- `savings_growth` and `investment_growth` are monotonically non-decreasing (given positive net monthly)
+
+---
+
+## Key Functions with Formal Specifications
+
+### get_cashflow_metrics
+
+```python
+def get_cashflow_metrics(db: Session, user_id: str, days: int = 90
+    ) -> tuple[float, float, float]:
+```
+
+**Preconditions:**
+- `days > 0`
+- `user_id` is a valid string (may reference a user with no accounts)
+
+**Postconditions:**
+- Returns `(current_balance, avg_daily_income, avg_daily_spending)` — all `>= 0.0`
+- If no accounts exist: returns `(0.0, 0.0, 0.0)`
+- If no transactions in window: returns `(current_balance, 0.0, 0.0)`
+- `avg_daily_income = total_credits_in_window / days`
+- `avg_daily_spending = total_debits_in_window / days`
+
+---
+
+### simulate_purchase_impact
+
+```python
+def simulate_purchase_impact(
+    db: Session, user_id: str, amount: float, category: str, merchant: str
+) -> dict:
+```
+
+**Preconditions:**
+- `amount > 0.0`
+- `category` and `merchant` are non-empty strings
+
+**Postconditions:**
+- `projected_balance = MAX(0.0, total_balance - amount)`
+- `risk_level` ∈ `{"low", "medium", "high", "critical"}`
+- `emergency_buffer_breached = (total_balance - amount) < emergency_threshold`
+- `recommendation` is a non-empty string
+
+---
+
+### simulate_investment_impact
+
+```python
+def simulate_investment_impact(
+    db: Session, user_id: str, monthly_sip: float, asset_type: str, lump_sum: float = 0.0
+) -> dict:
+```
+
+**Preconditions:**
+- `monthly_sip >= 0.0`
+- `lump_sum >= 0.0`
+- `asset_type` ∈ `{"stock", "crypto", "mutual_fund", "fd", "bond"}` (defaults to 7% APR for unknown)
+
+**Postconditions:**
+- `growth_projection` contains exactly 3 entries (year 1, 3, 5)
+- For each entry: `future_value >= total_invested` (compound growth is non-negative)
+- `is_affordable = (monthly_net >= monthly_sip)`
+
+---
+
+### stream_chat_response
+
+```python
+def stream_chat_response(db: Session, user_id: str, prompt: str
+    ) -> Generator[str, None, None]:
+```
+
+**Preconditions:**
+- `prompt` is a non-empty string
+- `user_id` references an existing user (or fallback user is used)
+
+**Postconditions:**
+- Yields at least one non-empty string chunk
+- After all chunks are yielded, `chat_memory` contains the user message and assembled assistant reply
+- History is capped at 12 messages (6 conversation rounds)
+- Never raises an exception to the caller — all backend errors are caught and a fallback chunk is yielded
+
+---
+
+### WebSocketConnectionManager.connect
+
+```python
+async def connect(self, websocket: WebSocket, user_id: str) -> None:
+```
+
+**Preconditions:**
+- `websocket` is an unaccepted FastAPI WebSocket instance
+- `user_id` is a non-empty string
+
+**Postconditions:**
+- `websocket.accept()` has been called
+- `user_id` key exists in `self.active_connections`
+- `websocket` is present in `self.active_connections[user_id]`
+- Multiple connections per user are supported (list, not single slot)
+
+---
+
+## Example Usage
+
+### 1. Balance Prediction (HTTP)
+
+```python
+import httpx
+
+# Get 90-day balance projection for the first user in DB
+response = httpx.get("http://localhost:8000/api/ai/twin/predict")
+data = response.json()
+
+# Expected shape:
+# {
+#   "current_balance": 12500.00,
+#   "projected_balance": 14200.00,
+#   "percent_change": 13.6,
+#   "net_daily": 18.89,
+#   "insight": "Based on current trends, your total balance is projected to grow...",
+#   "chart_data": [{"date": "2025-05-24", "balance": 12500.00}, ...]
+# }
+print(data["insight"])
+```
+
+### 2. Purchase Simulation (HTTP POST)
+
+```python
+response = httpx.post(
+    "http://localhost:8000/api/ai/simulate/purchase",
+    json={"amount": 3500.0, "merchant": "Tesla Dealership", "category": "Transport"}
+)
+data = response.json()
+
+# Expected shape:
+# {
+#   "risk_analysis": {"risk_level": "high", "reasons": [...]},
+#   "projected_balance": 9000.00,
+#   "recommendation": "⚠️ Refrain from this purchase if possible..."
+# }
+```
+
+### 3. Financial Health Score (HTTP)
+
+```python
+response = httpx.get("http://localhost:8000/api/ai/coaching/score")
+data = response.json()
+
+# Expected shape:
+# {
+#   "overall_score": 72.0,
+#   "categories": {
+#     "savings_consistency": {"score": 15.0, "max": 20},
+#     "debt_ratio": {"score": 18.0, "max": 20},
+#     ...
+#   },
+#   "explanation": "As a Saver, your financial health score of 72 reflects...",
+#   "actionable_improvements": ["Build savings buffer...", ...]
+# }
+```
+
+### 4. WebSocket Streaming Chat
+
+```python
+import asyncio
+import websockets
+import json
+
+async def chat():
+    uri = "ws://localhost:8000/api/ai/chat/ws"
+    async with websockets.connect(uri) as ws:
+        await ws.send(json.dumps({"type": "chat", "message": "What is my savings rate?"}))
+
+        full_reply = ""
+        async for raw in ws:
+            msg = json.loads(raw)
+            if msg["type"] == "chat_chunk":
+                full_reply += msg["content"]
+                print(msg["content"], end="", flush=True)
+            elif msg["type"] == "chat_end":
+                break
+
+asyncio.run(chat())
+```
+
+### 5. Fraud Evaluation (HTTP POST)
+
+```python
+# Evaluate a specific transaction
+response = httpx.post(
+    "http://localhost:8000/api/ai/fraud/evaluate/some-transaction-uuid"
+)
+data = response.json()
+
+# Expected shape:
+# {
+#   "fraud_risk_score": 65,
+#   "is_anomalous": true,
+#   "status": "flagged",
+#   "explanations": ["Amount is 3.5x historical average", "Unusual timing: 11PM–4AM"]
+# }
+```
+
+### 6. Subscription Optimization (HTTP)
+
+```python
+response = httpx.get("http://localhost:8000/api/ai/subscriptions/optimize")
+data = response.json()
+
+# Expected shape:
+# {
+#   "subscriptions": [...],
+#   "duplicates": [{"merchant": "Netflix", "count": 2, ...}],
+#   "unused_subscriptions": [{"merchant": "Gym", "yearly_savings": 240.0, ...}],
+#   "yearly_savings_potential": 240.0,
+#   "risk_analysis": [...]
+# }
+```
+
+---
+
+## Correctness Properties
+
+The following properties must hold universally across all valid inputs:
+
+Property 1: Balance non-negativity — For all users and projection windows,
+`projected_balance >= 0.0`. Balance is floored at zero; net negative cashflow
+cannot produce a negative projected balance.
+
+**Validates: Requirements 1.1**
+
+Property 2: Score boundedness — For all users,
+`0.0 <= overall_financial_health_score <= 100.0`. The score is clamped after
+summing all six sub-scores.
+
+**Validates: Requirements 1.2**
+
+Property 3: Score sub-score consistency — The sum of all six sub-scores equals
+`overall_score` before clamping. Each sub-score is non-negative and within its
+declared maximum (20, 20, 20, 20, 10, 10).
+
+**Validates: Requirements 1.2**
+
+Property 4: Fraud score boundedness — For all transactions,
+`0 <= fraud_risk_score <= 100`. The score is capped with `min(100, score)` after
+all rules are applied.
+
+**Validates: Requirements 1.3**
+
+Property 5: Fraud log idempotency — Evaluating the same transaction twice does not
+create duplicate `FraudLog` rows. The second call is a no-op if a log already exists
+for that `transaction_id`.
+
+**Validates: Requirements 1.3**
+
+Property 6: Cache transparency — For any endpoint with caching, the response returned
+from cache is semantically identical to a freshly computed response for the same
+`user_id` and parameters within the TTL window.
+
+**Validates: Requirements 1.4**
+
+Property 7: Chat memory cap — For any user,
+`len(chat_memory.get_history(user_id)) <= 12` at all times. History is trimmed to
+the last 12 messages after every addition.
+
+**Validates: Requirements 1.5**
+
+Property 8: Streaming completeness — Every `chat_start` WebSocket event is followed
+by zero or more `chat_chunk` events and exactly one `chat_end` event per request,
+regardless of which AI backend handles the response.
+
+**Validates: Requirements 1.5**
+
+Property 9: Insights non-empty — `analyze_spending_behavior` always returns at least
+one insight string. When no anomalies are detected, a stable-spending confirmation
+message is appended as the default.
+
+**Validates: Requirements 1.6**
+
+Property 10: Compound growth monotonicity — In `forecast_savings_and_investments`,
+given `net_monthly > 0`, the `savings_growth` and `investment_growth` arrays are
+monotonically non-decreasing across all months.
+
+**Validates: Requirements 1.1**
+
+Property 11: Debt decline monotonicity — The `debt_decline` array is monotonically
+non-increasing. Debt is reduced by `monthly_debt_payment` each month and floored at
+zero; it never increases in the projection model.
+
+**Validates: Requirements 1.1**
+
+Property 12: DB fallback transparency — All AI engine functions behave identically
+whether the underlying engine is PostgreSQL or SQLite. No engine-specific SQL syntax
+is used; all queries go through the SQLAlchemy ORM.
+
+**Validates: Requirements 1.7**
+
+Property 13: AI backend fallback completeness — `get_chat_response` and
+`stream_chat_response` always return a non-empty response regardless of which AI
+backends are available, including when all external backends are offline (the
+offline rule-based fallback is invoked).
+
+**Validates: Requirements 1.8**
+
+Property 14: WebSocket multi-connection — A single `user_id` can have multiple
+simultaneous WebSocket connections. `send_personal_message` delivers the message
+to all active connections for that user.
+
+**Validates: Requirements 1.5**
+
+---
+
+## Error Handling
+
+### Scenario 1: PostgreSQL Unavailable
+
+**Condition**: `OperationalError` raised during engine connection test at startup.
+**Response**: `database.py` catches the exception, logs a warning, and re-initializes
+the engine with `sqlite:///./bankbot.db` and `check_same_thread=False`.
+**Recovery**: All subsequent DB operations use SQLite transparently. No restart required.
+
+---
+
+### Scenario 2: Redis Unavailable
+
+**Condition**: `redis.Redis.ping()` raises an exception or `redis` library is not installed.
+**Response**: `CacheManager.__init__` catches the exception, sets `use_redis = False`,
+and all cache operations route to `MemoryCache`.
+**Recovery**: In-memory cache is thread-safe via `threading.Lock`. TTL eviction is
+lazy (checked on `get`). Cache is lost on process restart (acceptable for dev/staging).
+
+---
+
+### Scenario 3: All AI Backends Offline
+
+**Condition**: `OPENAI_API_KEY` and `GROQ_API_KEY` are unset; local Ollama is unreachable.
+**Response**: `has_active_ai_backend()` returns `False`. `get_chat_response` and
+`generate_daily_briefing` invoke `get_offline_chat_fallback()` which generates a
+rule-based, data-grounded response from the user's DB records.
+**Recovery**: Responses are still financially meaningful (use real scores and balances).
+No exception is surfaced to the API caller.
+
+---
+
+### Scenario 4: User Not Found
+
+**Condition**: `user_id` query param is absent or references a non-existent user.
+**Response**: `get_user_id_fallback()` in `router.py` queries the first available user.
+If no users exist, raises `HTTPException(404, "No users found. Seed the database first.")`.
+**Recovery**: Run `python backend/app/scripts/seed.py` to populate the database.
+
+---
+
+### Scenario 5: WebSocket Client Disconnects Unexpectedly
+
+**Condition**: `WebSocketDisconnect` raised during `websocket.receive_text()`.
+**Response**: `websocket/router.py` catches `WebSocketDisconnect`, calls
+`ws_manager.disconnect(websocket, user_id)`, and closes the DB session in `finally`.
+**Recovery**: Client can reconnect; server state is clean. Chat history is preserved
+in `ChatMemoryManager` for the session duration.
+
+---
+
+### Scenario 6: Transaction Not Found for Fraud Evaluation
+
+**Condition**: `POST /api/ai/fraud/evaluate/{transaction_id}` with a non-existent ID.
+**Response**: `evaluate_transaction_for_fraud` returns `{"error": "Transaction not found"}`.
+**Recovery**: Caller should verify the transaction ID before calling the endpoint.
+
+---
+
+### Scenario 7: OpenAI / Groq API Error During Streaming
+
+**Condition**: Network error or rate limit during `stream_chat_response`.
+**Response**: The exception is caught per-backend; the next backend in the fallback
+chain is attempted. If all fail, `get_offline_chat_fallback()` result is yielded as
+a single chunk.
+**Recovery**: Streaming continues without interruption from the client's perspective.
+
+---
+
+## Testing Strategy
+
+### Unit Testing Approach
+
+Each AI engine module is tested in isolation with a mocked SQLAlchemy session.
+Key test cases per module:
+
+- **forecasting.py**: Zero-transaction user returns `(balance, 0.0, 0.0)`;
+  negative net daily floors projected balance at 0.0; chart_data length matches
+  `ceil(projection_days / 5) + 1`.
+- **coaching.py**: Score is always in `[0, 100]`; improvements list is non-empty;
+  all six sub-scores are within their declared maximums.
+- **fraud.py**: Score caps at 100 even when multiple rules fire simultaneously;
+  duplicate FraudLog is not created on second evaluation of same transaction.
+- **behavior.py**: Returns at least one insight for any input including empty transaction list.
+- **simulation.py**: `projected_balance >= 0` for any purchase amount; investment
+  growth projection always has exactly 3 entries.
+- **cache.py**: MemoryCache TTL eviction works correctly; expired keys return `None`.
+
+### Property-Based Testing Approach
+
+**Property Test Library**: `hypothesis` (Python)
+
+Key properties to test with generated inputs:
+
+```python
+from hypothesis import given, strategies as st
+
+@given(st.floats(min_value=0, max_value=1e9), st.floats(min_value=0, max_value=1e6))
+def test_projected_balance_non_negative(current_balance, net_daily_loss):
+    """projected_balance is always >= 0 regardless of net daily cashflow."""
+    result = max(0.0, current_balance - net_daily_loss * 90)
+    assert result >= 0.0
+
+@given(st.floats(min_value=0, max_value=1e6), st.floats(min_value=0, max_value=1e6),
+       st.floats(min_value=0, max_value=1e6), st.floats(min_value=0, max_value=1e6),
+       st.floats(min_value=0, max_value=1e6), st.floats(min_value=0, max_value=1e6))
+def test_health_score_bounded(s1, s2, s3, s4, s5, s6):
+    """Financial health score is always in [0, 100]."""
+    raw = s1 + s2 + s3 + s4 + s5 + s6
+    score = min(100.0, max(0.0, raw))
+    assert 0.0 <= score <= 100.0
+
+@given(st.integers(min_value=0, max_value=500))
+def test_fraud_score_bounded(rule_score_sum):
+    """Fraud score is always capped at 100."""
+    score = min(100, rule_score_sum)
+    assert 0 <= score <= 100
+```
+
+### Integration Testing Approach
+
+1. **Database Fallback**: Start with `DATABASE_URL` pointing to an unreachable host;
+   verify `engine` uses SQLite and `Base.metadata.create_all()` succeeds.
+2. **Seed + Endpoint Round-trip**: Run `seed.py`, then call all GET endpoints via
+   `httpx`; assert all return HTTP 200 with non-empty JSON bodies.
+3. **WebSocket Chat**: Open a WebSocket connection, send a chat message, collect all
+   chunks until `chat_end`, assert the assembled reply is a non-empty string.
+4. **Cache Hit Verification**: Call a cached endpoint twice; assert the second call
+   returns within 10ms (cache hit) and the response is identical.
+5. **Fraud Idempotency**: Call `POST /api/ai/fraud/evaluate/{id}` twice for the same
+   transaction; assert only one `FraudLog` row exists in the DB.
+
+---
+
+## Performance Considerations
+
+- **Cache TTLs are tuned by endpoint cost**: Briefings (LLM-heavy) cache for 3600s;
+  behavioral insights cache for 600s; balance projections cache for 300s.
+- **Chat history is capped at 12 messages** to bound the token count sent to LLMs
+  and prevent context window overflow.
+- **AI backend detection is done once at module load time** (`AI_BACKEND_AVAILABLE`
+  flag in `ollama_integration.py`) to avoid per-request timeout delays.
+- **Fraud history window is capped at 30 transactions** to keep anomaly detection O(1)
+  in practice.
+- **WebSocket streaming** avoids buffering the full LLM response before delivery,
+  reducing perceived latency for the user.
+- **SQLite WAL mode** should be enabled for concurrent read performance if multiple
+  workers are used with the SQLite fallback.
+
+---
+
+## Security Considerations
+
+- **No authentication on AI endpoints** in the current implementation — `user_id` is
+  passed as a query parameter. Production deployment must add JWT middleware to
+  validate that the requesting user can only access their own data.
+- **API keys** (`OPENAI_API_KEY`, `GROQ_API_KEY`) are read from environment variables
+  and never logged or returned in API responses.
+- **SQL injection** is not possible — all DB queries use SQLAlchemy ORM with
+  parameterized bindings.
+- **WebSocket origin validation** is not enforced in development. Production should
+  restrict `allow_origins` in CORS middleware and validate WebSocket upgrade headers.
+- **Fraud log writes** are the only DB mutations in the AI layer; all other operations
+  are read-only, limiting the blast radius of any AI module bug.
+- **LLM prompt injection**: User chat messages are passed as `role: user` content,
+  not interpolated into the system prompt, reducing prompt injection risk.
+
+---
+
+## Dependencies
+
+| Package | Purpose | Notes |
+|---------|---------|-------|
+| `fastapi` | HTTP and WebSocket framework | Core API layer |
+| `uvicorn` | ASGI server | Run with `uvicorn app.main:app` |
+| `sqlalchemy` | ORM and DB abstraction | PostgreSQL + SQLite |
+| `psycopg2-binary` | PostgreSQL driver | Falls back gracefully if PG unavailable |
+| `openai` | OpenAI API client | `gpt-4o-mini` default model |
+| `groq` | Groq API client | `llama-3.3-70b-versatile` fallback |
+| `requests` | HTTP client for Ollama | Local Ollama REST API |
+| `redis` | Redis client | Optional; falls back to MemoryCache |
+| `numpy` | Statistical computations | Mean, stddev for fraud/behavior |
+| `langchain` | LLM orchestration | Listed in requirements; available for future chain-based features |
+| `pydantic` | Request/response validation | Pydantic v2 compatible |
+| `hypothesis` | Property-based testing | Dev dependency |
+| `httpx` | Async HTTP client for tests | Dev dependency |
+| `websockets` | WebSocket client for tests | Dev dependency |

.kiro/specs/bankbot-ai-intelligence/tasks.md

@@ -0,0 +1,286 @@
+# Tasks: BankBot AI Intelligence & API (Phase 4)
+
+## Implementation Status Summary
+
+After a full codebase audit, the majority of Phase 4 is already implemented. The tasks below
+reflect the **actual gaps** between the current code and the design specification — not a
+from-scratch build. Each task is scoped to what genuinely needs to be done.
+
+---
+
+## Task 1: Fix requirements.txt — Add Missing Dependencies
+
+**Status**: ✅ Complete  
+**Priority**: Critical (blocks everything else)  
+**File**: `backend/requirements.txt`
+
+The current `requirements.txt` is missing several packages that the AI layer actively imports.
+Running the backend without these will cause `ImportError` crashes.
+
+- [ ] 1.1 Add `groq` — required by `ollama_integration.py` (`from groq import Groq`)
+- [ ] 1.2 Add `redis` — required by `middleware/cache.py` (`import redis`)
+- [ ] 1.3 Add `numpy` — required by `ai/fraud.py` and `ai/behavior.py` (`import numpy as np`)
+- [ ] 1.4 Add `httpx` — required for endpoint validation scripts
+- [ ] 1.5 Add `websockets` — required for WebSocket test script
+- [ ] 1.6 Add `python-dotenv` — required to load `.env` file when running locally
+- [ ] 1.7 Pin versions for all new additions (e.g. `groq==0.9.0`, `redis==5.0.4`, `numpy==1.26.4`)
+
+**Acceptance**: `pip install -r requirements.txt` completes without errors in a clean venv.
+
+---
+
+## Task 2: Extend ollama_integration.py — Add OpenAI to Unified Wrapper
+
+**Status**: ✅ Complete  
+**Priority**: High  
+**File**: `backend/app/ai/ollama_integration.py`
+
+The `get_ai_response()` and `stream_ai_response()` unified wrappers currently only route to
+Groq or Ollama. The design specifies OpenAI as the **first priority** in the fallback chain.
+`chat.py` and `coaching.py` implement OpenAI directly, but `ollama_integration.py` — which
+is the shared backend abstraction — does not.
+
+- [ ] 2.1 Add `get_openai_response(prompt, history, model, language)` function that calls
+  `openai.OpenAI(api_key=OPENAI_API_KEY).chat.completions.create(...)` with the configured
+  model (default `gpt-4o-mini`, read from `OPENAI_MODEL` env var)
+- [ ] 2.2 Add `stream_openai_response(prompt, history, model, language)` generator that
+  calls the same endpoint with `stream=True` and yields content chunks
+- [ ] 2.3 Update `get_ai_response()` to try OpenAI first, then Groq, then Ollama:
+  ```python
+  if OPENAI_API_KEY:
+      result = get_openai_response(...)
+      if result: return result
+  if GROQ_API_KEY:
+      result = get_groq_response(...)
+      if result: return result
+  return get_ollama_response(...)
+  ```
+- [ ] 2.4 Update `stream_ai_response()` with the same three-tier priority order
+- [ ] 2.5 Update `AI_BACKEND_AVAILABLE` detection at module load to also check `OPENAI_API_KEY`
+  (it already does — verify the logic is correct and add a comment)
+- [ ] 2.6 Add `OPENAI_MODEL = os.environ.get("OPENAI_MODEL", "gpt-4o-mini")` constant at
+  the top of the file so the model is configurable without code changes
+
+**Acceptance**: With `OPENAI_API_KEY` set, `get_ai_response("test")` returns an OpenAI
+response. With only `GROQ_API_KEY` set, it falls back to Groq. With neither, it falls back
+to Ollama or returns `None`.
+
+---
+
+## Task 3: Update .env.example — Document All AI & Cache Variables
+
+**Status**: ✅ Complete  
+**Priority**: High  
+**File**: `.env.example`
+
+The `.env.example` needs to document every environment variable the Phase 4 AI layer reads,
+so any developer can get the app running immediately.
+
+- [ ] 3.1 Add `OPENAI_API_KEY=your_openai_key_here`
+- [ ] 3.2 Add `OPENAI_MODEL=gpt-4o-mini`
+- [ ] 3.3 Add `GROQ_API_KEY=your_groq_key_here`
+- [ ] 3.4 Add `OLLAMA_MODEL=llama3:latest`
+- [ ] 3.5 Add `REDIS_URL=redis://localhost:6379/0`
+- [ ] 3.6 Add `USE_SQLITE=true` with a comment explaining it forces SQLite fallback
+- [ ] 3.7 Add `DATABASE_URL=postgresql://admin:adminpassword@localhost:5432/bankbot`
+- [ ] 3.8 Add a comment block at the top explaining the fallback priority chain:
+  `# AI: OpenAI → Groq → Ollama → offline fallback`
+  `# DB: PostgreSQL → SQLite`
+  `# Cache: Redis → in-memory TTL dict`
+
+**Acceptance**: A developer can copy `.env.example` to `.env`, fill in one API key, and
+the backend starts without any missing-variable errors.
+
+---
+
+## Task 4: Validate and Harden seed.py
+
+**Status**: ✅ Complete  
+**Priority**: Medium  
+**File**: `backend/app/scripts/seed.py`
+
+The seed script works but has one logic bug: the `db.commit()` inside the transaction loop
+commits after every single transaction, which is slow and can leave partial state on error.
+Also, the script does not print which DB backend it seeded into.
+
+- [ ] 4.1 Move `db.commit()` out of the per-transaction loop — commit once per user after
+  all their transactions, goals, investments, and subscriptions are added
+- [ ] 4.2 Add a `try/except/rollback` block around the per-user seeding so a failure on
+  one user does not corrupt the others
+- [ ] 4.3 Print the active database URL at the start of `seed_data()` so the developer
+  knows whether SQLite or PostgreSQL was used:
+  ```python
+  from app.database.database import SQLALCHEMY_DATABASE_URL
+  print(f"Seeding into: {SQLALCHEMY_DATABASE_URL}")
+  ```
+- [ ] 4.4 Add a second subscription per user (e.g. Spotify at $9.99/month with
+  `usage_frequency: "low"`) so the subscription optimizer has data to detect unused subs
+- [ ] 4.5 Add a duplicate subscription for one user (two Netflix entries) so the duplicate
+  detection logic in `subscriptions.py` has a real test case
+- [ ] 4.6 Add a late-night transaction (timestamp hour = 23 or 0) for at least one user
+  so `behavior.py` late-night detection fires on seeded data
+
+**Acceptance**: Running `python backend/app/scripts/seed.py` twice: first run seeds 5 users
+and prints "Database seeded successfully!"; second run prints "Database already seeded." and
+exits cleanly. The `subscriptions/optimize` endpoint returns at least one unused subscription
+and one duplicate after seeding.
+
+---
+
+## Task 5: Build test_endpoints.py — Full HTTP Validation Script
+
+**Status**: ✅ Complete  
+**Priority**: High  
+**File**: `backend/app/scripts/test_endpoints.py`
+
+The current `test_endpoints.py` needs to be a real validation script that calls every AI
+endpoint and asserts the response shape is correct.
+
+- [ ] 5.1 Import `httpx` and define `BASE_URL = "http://localhost:8000"`
+- [ ] 5.2 Add a `get_first_user_id()` helper that calls `GET /api/ai/coaching/score` without
+  a `user_id` param (uses the fallback) and extracts the user from the response, or queries
+  the DB directly via `seed.py`'s session
+- [ ] 5.3 Test `GET /api/ai/twin/predict` — assert `200`, assert keys
+  `current_balance`, `projected_balance`, `chart_data` exist, assert `len(chart_data) >= 1`
+- [ ] 5.4 Test `GET /api/ai/twin/future` — assert `200`, assert `savings_growth` and
+  `investment_growth` are non-empty lists
+- [ ] 5.5 Test `GET /api/ai/twin/scenarios` — assert `200`, assert keys `status_quo`,
+  `frugal`, `lifestyle_inflation` all present
+- [ ] 5.6 Test `POST /api/ai/simulate/purchase` with body
+  `{"amount": 500.0, "merchant": "Test", "category": "Shopping"}` — assert `200`,
+  assert `risk_analysis.risk_level` is one of `low/medium/high/critical`
+- [ ] 5.7 Test `POST /api/ai/simulate/investment` with body
+  `{"monthly_sip": 200.0, "asset_type": "stock"}` — assert `200`,
+  assert `growth_projection` has exactly 3 entries (year 1, 3, 5)
+- [ ] 5.8 Test `GET /api/ai/behavior/insights` — assert `200`, assert `insights` is a
+  non-empty list
+- [ ] 5.9 Test `GET /api/ai/coaching/score` — assert `200`, assert `overall_score` is
+  between 0 and 100, assert all 6 category keys are present
+- [ ] 5.10 Test `GET /api/ai/coaching/briefing` — assert `200`, assert `briefing` is a
+  non-empty string
+- [ ] 5.11 Test `GET /api/ai/subscriptions/optimize` — assert `200`, assert `subscriptions`
+  key exists
+- [ ] 5.12 Test `GET /api/ai/fraud/analysis` — assert `200`, assert `total_alerts` key exists
+- [ ] 5.13 Test `POST /api/ai/chat` with body `{"message": "What is my savings rate?"}` —
+  assert `200`, assert `response` is a non-empty string
+- [ ] 5.14 Print a pass/fail summary table at the end showing each endpoint and its result
+- [ ] 5.15 Exit with code `1` if any test fails so CI can detect failures
+
+**Acceptance**: Running `python backend/app/scripts/test_endpoints.py` with the server
+running prints a table where all 13 endpoints show PASS.
+
+---
+
+## Task 6: Build test_websocket.py — WebSocket Streaming Validation Script
+
+**Status**: ✅ Complete  
+**Priority**: High  
+**File**: `backend/app/scripts/test_websocket.py` (new file)
+
+No WebSocket test script exists. This is required by the verification plan.
+
+- [ ] 6.1 Create `backend/app/scripts/test_websocket.py`
+- [ ] 6.2 Import `asyncio`, `websockets`, `json`
+- [ ] 6.3 Write `async def test_chat_streaming()`:
+  - Connect to `ws://localhost:8000/api/ai/chat/ws`
+  - Send `{"type": "chat", "message": "What is my current balance?"}`
+  - Collect all messages until `type == "chat_end"`
+  - Assert at least one `chat_chunk` was received
+  - Assert the assembled reply is a non-empty string
+  - Print the full assembled reply
+- [ ] 6.4 Write `async def test_ping_pong()`:
+  - Connect to the same endpoint
+  - Send `{"type": "ping"}`
+  - Assert the response is `{"type": "pong"}`
+- [ ] 6.5 Write `async def test_invalid_json()`:
+  - Send a raw non-JSON string
+  - Assert the response contains `{"type": "error"}`
+- [ ] 6.6 Run all three tests in `asyncio.run(main())` and print pass/fail for each
+- [ ] 6.7 Exit with code `1` if any test fails
+
+**Acceptance**: Running `python backend/app/scripts/test_websocket.py` with the server
+running prints three PASS lines and exits with code 0.
+
+---
+
+## Task 7: Add CORS Hardening and Health Endpoint to main.py
+
+**Status**: ✅ Complete  
+**Priority**: Low (dev environment acceptable, note for production)  
+**File**: `backend/app/main.py`
+
+- [ ] 7.1 Add a `GET /api/ai/status` endpoint that returns the active AI backend, DB type,
+  and cache type — useful for debugging without reading logs:
+  ```python
+  @app.get("/api/ai/status")
+  def ai_status():
+      from app.ai.ollama_integration import has_active_ai_backend, OPENAI_API_KEY, GROQ_API_KEY
+      from app.middleware.cache import cache
+      from app.database.database import SQLALCHEMY_DATABASE_URL
+      return {
+          "ai_backend": "openai" if OPENAI_API_KEY else "groq" if GROQ_API_KEY else "ollama",
+          "ai_available": has_active_ai_backend(),
+          "db_type": "sqlite" if "sqlite" in SQLALCHEMY_DATABASE_URL else "postgresql",
+          "cache_type": "redis" if cache.use_redis else "memory"
+      }
+  ```
+- [ ] 7.2 Add a comment above `allow_origins=["*"]` noting it must be restricted to the
+  frontend origin in production (e.g. `["http://localhost:3000"]`)
+
+**Acceptance**: `GET /api/ai/status` returns a JSON object with all four fields populated
+correctly based on the active environment.
+
+---
+
+## Task 8: Verify Full Stack Runs End-to-End
+
+**Status**: ✅ Complete — verified 2025-05-24  
+**Priority**: Critical  
+**This is the final integration verification task.**
+
+- [ ] 8.1 Install dependencies: `pip install -r backend/requirements.txt`
+- [ ] 8.2 Seed the database: `python backend/app/scripts/seed.py`
+  - Confirm output: `Seeding into: sqlite:///...` and `Database seeded successfully!`
+- [ ] 8.3 Start the backend: `uvicorn app.main:app --reload` from `backend/`
+  - Confirm output: `Initializing database...` and `Database initialization complete.`
+  - Confirm no `ImportError` or `ModuleNotFoundError` in startup logs
+- [ ] 8.4 Open Swagger UI at `http://localhost:8000/docs`
+  - Confirm all 13 AI endpoints appear under the `AI Intelligence` tag
+  - Confirm the WebSocket endpoint appears under `WebSockets`
+- [ ] 8.5 Run HTTP validation: `python backend/app/scripts/test_endpoints.py`
+  - Confirm all 13 endpoints return PASS
+- [ ] 8.6 Run WebSocket validation: `python backend/app/scripts/test_websocket.py`
+  - Confirm all 3 WebSocket tests return PASS
+- [ ] 8.7 Check `GET /api/ai/status` returns correct backend/db/cache values
+- [ ] 8.8 Manually call `GET /api/ai/coaching/score` via Swagger UI and confirm the
+  response contains `overall_score` between 0–100 and all 6 sub-score categories
+
+**Acceptance**: All 8 sub-tasks complete without errors. The backend is fully operational
+with SQLite fallback and in-memory cache, ready for frontend integration.
+
+---
+
+## Dependency Map
+
+```
+Task 1 (requirements.txt)
+  └── Task 2 (ollama_integration OpenAI)
+  └── Task 5 (test_endpoints — needs httpx)
+  └── Task 6 (test_websocket — needs websockets)
+
+Task 3 (.env.example) — independent
+
+Task 4 (seed.py hardening)
+  └── Task 8.2 (seeding step in final verification)
+
+Task 2 (ollama_integration)
+  └── Task 8 (full stack verification)
+
+Task 5 + Task 6 (test scripts)
+  └── Task 8.5 + 8.6
+
+Task 7 (status endpoint)
+  └── Task 8.7
+```
+
+**Recommended execution order**: 1 → 3 → 4 → 2 → 7 → 5 → 6 → 8

.vscode/settings.json

@@ -0,0 +1,2 @@
+{
+}

Dockerfile

@@ -0,0 +1,101 @@
+# ============================================================
+# BankBot AI — Hugging Face Spaces Dockerfile
+#
+# Single-container deployment:
+#   Port 7860 (HF requirement) → Nginx
+#   Nginx → Next.js (port 3000) for frontend
+#   Nginx → FastAPI (port 8000) for /api/* and /ws
+#
+# Build args:
+#   NEXT_PUBLIC_API_URL  (default: relative /api proxy)
+# ============================================================
+
+# ─── Stage 1: Build Next.js frontend ─────────────────────────────────────────
+FROM node:20-alpine AS frontend-builder
+
+WORKDIR /frontend
+
+COPY frontend/package.json frontend/package-lock.json* ./
+RUN npm ci --legacy-peer-deps --quiet
+
+COPY frontend/ .
+
+# In HF, frontend calls go through the same origin via Nginx proxy
+# So NEXT_PUBLIC_API_URL is empty — rewrites handle /api/* internally
+ARG NEXT_PUBLIC_API_URL=""
+ENV NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL
+ENV NEXT_TELEMETRY_DISABLED=1
+
+RUN npm run build
+
+# ─── Stage 2: Python dependencies ────────────────────────────────────────────
+FROM python:3.11-slim AS python-builder
+
+WORKDIR /build
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    libpq-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY backend/requirements.txt .
+RUN pip install --no-cache-dir --prefix=/install -r requirements.txt
+
+# ─── Stage 3: Final runtime image ────────────────────────────────────────────
+FROM python:3.11-slim AS runtime
+
+# Install Node.js, Nginx, supervisord, curl
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    nginx \
+    supervisor \
+    curl \
+    libpq5 \
+    ca-certificates \
+    && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+    && apt-get install -y --no-install-recommends nodejs \
+    && rm -rf /var/lib/apt/lists/*
+
+# ── Python packages ───────────────────────────────────────────────────────────
+COPY --from=python-builder /install /usr/local
+
+# ── Backend ───────────────────────────────────────────────────────────────────
+WORKDIR /app/backend
+COPY backend/app/ ./app/
+COPY backend/requirements.txt .
+
+# ── Frontend (standalone build) ───────────────────────────────────────────────
+WORKDIR /app/frontend
+COPY --from=frontend-builder /frontend/.next/standalone ./
+COPY --from=frontend-builder /frontend/.next/static ./.next/static
+COPY --from=frontend-builder /frontend/public ./public
+
+# ── Nginx config ──────────────────────────────────────────────────────────────
+COPY hf/nginx.conf /etc/nginx/nginx.conf
+
+# ── Supervisord config ────────────────────────────────────────────────────────
+COPY hf/supervisord.conf /etc/supervisor/conf.d/bankbot.conf
+
+# ── Startup script ────────────────────────────────────────────────────────────
+COPY hf/start.sh /app/start.sh
+RUN chmod +x /app/start.sh
+
+# ── Writable dirs for non-root (HF runs as user 1000) ────────────────────────
+RUN mkdir -p /app/data /var/log/supervisor /var/log/nginx /var/lib/nginx/body \
+    && chmod -R 777 /app/data /var/log/supervisor /var/log/nginx \
+    && chmod -R 777 /var/lib/nginx \
+    && touch /run/nginx.pid && chmod 777 /run/nginx.pid \
+    && chown -R 1000:1000 /app /var/log/supervisor /var/log/nginx /var/lib/nginx
+
+# HF Spaces requires port 7860
+EXPOSE 7860
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=15s --start-period=60s --retries=5 \
+    CMD curl -f http://localhost:7860/health || exit 1
+
+# Run as user 1000 (HF default)
+USER 1000
+
+WORKDIR /app
+
+CMD ["/app/start.sh"]

README.md

@@ -0,0 +1,186 @@
+---
+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
+---
+
+<div align="center">
+
+# 🏦 BankBot AI
+
+### AI-Native Financial Operating System
+
+[![FastAPI](https://img.shields.io/badge/FastAPI-009688?style=flat-square&logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com)
+[![Next.js](https://img.shields.io/badge/Next.js_14-black?style=flat-square&logo=next.js&logoColor=white)](https://nextjs.org)
+[![Python](https://img.shields.io/badge/Python_3.11-3776AB?style=flat-square&logo=python&logoColor=white)](https://python.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://typescriptlang.org)
+[![Docker](https://img.shields.io/badge/Docker-2496ED?style=flat-square&logo=docker&logoColor=white)](https://docker.com)
+[![OpenAI](https://img.shields.io/badge/OpenAI-412991?style=flat-square&logo=openai&logoColor=white)](https://openai.com)
+
+**A production-grade AI fintech platform** with real-time WebSocket streaming, multi-provider AI fallback, fraud detection, financial forecasting, and a premium glassmorphism UI.
+
+</div>
+
+---
+
+## 🚀 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](https://github.com/your-username/bankbot-ai)
+
+Documentation:
+- [Architecture](./docs/ARCHITECTURE.md)
+- [API Reference](./docs/API_DOCUMENTATION.md)
+- [Deployment Guide](./docs/DEPLOYMENT_GUIDE.md)
+- [ER Diagram](./docs/ER_DIAGRAM.md)

backend/Dockerfile

@@ -0,0 +1,44 @@
+# ─── Stage 1: Builder ────────────────────────────────────────────────────────
+FROM python:3.11-slim AS builder
+
+WORKDIR /build
+
+# System deps for psycopg2 and cryptography
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    libpq-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir --prefix=/install -r requirements.txt
+
+# ─── Stage 2: Runtime ────────────────────────────────────────────────────────
+FROM python:3.11-slim AS runtime
+
+WORKDIR /app
+
+# Runtime system deps only
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libpq5 \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy installed packages from builder
+COPY --from=builder /install /usr/local
+
+# Copy application code (exclude venv, __pycache__, .env)
+COPY app/ ./app/
+COPY requirements.txt .
+
+# Non-root user for security
+RUN useradd -m -u 1001 bankbot && chown -R bankbot:bankbot /app
+USER bankbot
+
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=15s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Production: no --reload, multiple workers
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "2", "--proxy-headers", "--forwarded-allow-ips", "*"]

backend/alembic.ini

@@ -0,0 +1,80 @@
+# A generic, single database configuration.
+
+[alembic]
+# path to migration scripts
+script_location = alembic
+
+# template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
+# file_template = %%(rev)s_%%(slug)s
+
+# timezone to use when rendering the date within the migration file
+# timezone = UTC
+
+# max length of characters to apply to the
+# "slug" field
+# truncate_slug_length = 40
+
+# set to 'true' to run the environment during
+# the 'revision' command, regardless of autogenerate
+# revision_environment = false
+
+# set to 'true' to allow .pyc and .pyo files without
+# a source .py file to be detected as revisions in the
+# versions/ directory
+# sourceless = false
+
+# version location specification; This defaults
+# to alembic/versions.  When using multiple version
+# directories, initial revisions must be specified with --version-path.
+# version_locations = %(here)s/bar:%(here)s/bat:alembic/versions
+
+# the output encoding used when revision files
+# are written from script.py.mako
+# output_encoding = utf-8
+
+sqlalchemy.url = postgresql://admin:adminpassword@localhost:5432/bankbot
+
+[post_write_hooks]
+# post_write_hooks defines scripts or Python functions that are run
+# on newly generated revision scripts.  See the documentation for further
+# detail and examples
+
+# format using "black" - use the console_scripts runner, against the "black" entrypoint
+# hooks = black
+# black.type = console_scripts
+# black.entrypoint = black
+# black.options = -l 79 REVISION_SCRIPT_FILENAME
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

backend/alembic/env.py

@@ -0,0 +1,81 @@
+from logging.config import fileConfig
+import os
+import sys
+
+from sqlalchemy import engine_from_config
+from sqlalchemy import pool
+
+from alembic import context
+
+# Add parent directory to path to import app modules
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from app.database.models import Base
+from app.database.database import SQLALCHEMY_DATABASE_URL
+
+# this is the Alembic Config object, which provides
+# access to the values within the .ini file in use.
+config = context.config
+
+# Interpret the config file for Python logging.
+# This line sets up loggers basically.
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# add your model's MetaData object here
+# for 'autogenerate' support
+target_metadata = Base.metadata
+
+# Set sqlalchemy.url from the environment or default
+config.set_main_option("sqlalchemy.url", SQLALCHEMY_DATABASE_URL)
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode.
+
+    This configures the context with just a URL
+    and not an Engine, though an Engine is acceptable
+    here as well.  By skipping the Engine creation
+    we don't even need a DBAPI to be available.
+
+    Calls to context.execute() here emit the given string to the
+    script output.
+
+    """
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode.
+
+    In this scenario we need to create an Engine
+    and associate a connection with the context.
+
+    """
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection, target_metadata=target_metadata
+        )
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

backend/alembic/script.py.mako

@@ -0,0 +1,26 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

backend/app/ai/behavior.py

@@ -0,0 +1,138 @@
+from datetime import datetime, timedelta
+from collections import defaultdict
+import numpy as np
+from sqlalchemy.orm import Session
+from app.database.models import Account, Transaction
+
+def analyze_spending_behavior(db: Session, user_id: str, days: int = 90):
+    """
+    Analyzes historical transactions to detect behavioral patterns (late-night, impulsive, dopamine, stress).
+    """
+    accounts = db.query(Account).filter(Account.user_id == user_id).all()
+    account_ids = [acc.id for acc in accounts]
+    
+    if not account_ids:
+        return {"insights": [], "metrics": {}}
+        
+    cutoff = datetime.utcnow() - timedelta(days=days)
+    txns = db.query(Transaction).filter(
+        Transaction.account_id.in_(account_ids),
+        Transaction.timestamp >= cutoff,
+        Transaction.type == "debit"
+    ).all()
+    
+    if not txns:
+        return {
+            "insights": ["No recent debit transactions to analyze. Complete a few purchases to start behavioral profiling."],
+            "metrics": {
+                "late_night_count": 0,
+                "late_night_total": 0.0,
+                "weekend_pct": 0.0,
+                "impulsive_count": 0,
+                "impulsive_total": 0.0,
+                "dopamine_count": 0,
+                "stress_count": 0
+            }
+        }
+        
+    # Analyze variables
+    late_night_txns = []
+    weekend_txns = []
+    impulsive_txns = []
+    dopamine_txns = []
+    stress_txns = []
+    
+    amounts = [t.amount for t in txns]
+    avg_txn = np.mean(amounts)
+    std_txn = np.std(amounts) if len(amounts) > 1 else 0.0
+    
+    category_totals = defaultdict(float)
+    hourly_counts = defaultdict(int)
+    
+    for t in txns:
+        # Categorize
+        category_totals[t.category or "Other"] += t.amount
+        
+        # Timing
+        hour = t.timestamp.hour
+        hourly_counts[hour] += 1
+        
+        # Late-night spending (11PM to 4AM)
+        if hour >= 23 or hour < 4:
+            late_night_txns.append(t)
+            
+        # Weekend spending (Friday, Saturday, Sunday)
+        # weekday() is 0=Monday, 4=Friday, 5=Saturday, 6=Sunday
+        day = t.timestamp.weekday()
+        if day in [4, 5, 6]:
+            weekend_txns.append(t)
+            
+        # Impulsive spending (More than average + 1.5 * standard dev, or marked as 'regret')
+        if t.amount > (avg_txn + 1.5 * std_txn) and (t.category in ["Shopping", "Entertainment", "Food"]):
+            impulsive_txns.append(t)
+            
+        # Emotion tags
+        emotion = (t.spending_emotion_label or "").lower()
+        if emotion == "regret":
+            stress_txns.append(t)
+        elif emotion in ["happy", "dopamine"] or (t.category == "Shopping" and t.amount > avg_txn):
+            dopamine_txns.append(t)
+            
+    # Insights construction
+    insights = []
+    
+    # 1. Late night alert
+    late_night_pct = (len(late_night_txns) / len(txns) * 100) if txns else 0
+    if late_night_pct > 15:
+        total_late = sum(t.amount for t in late_night_txns)
+        insights.append(
+            f"🌙 High late-night spending: {late_night_pct:.1f}% of transactions occur after 11PM (Total: ${total_late:,.2f}). "
+            "Consider setting a bedtime blocker on your bank card."
+        )
+        
+    # 2. Weekend overspending
+    weekend_pct = (len(weekend_txns) / len(txns) * 100) if txns else 0
+    if weekend_pct > 45:
+        weekend_avg = np.mean([t.amount for t in weekend_txns]) if weekend_txns else 0
+        weekday_txns = [t for t in txns if t not in weekend_txns]
+        weekday_avg = np.mean([t.amount for t in weekday_txns]) if weekday_txns else 0
+        
+        if weekend_avg > weekday_avg * 1.2:
+            pct_diff = ((weekend_avg - weekday_avg) / weekday_avg) * 100
+            insights.append(
+                f"🎉 Weekend Spikes: You spend {pct_diff:.1f}% more on weekends than weekdays. "
+                "Mainly driven by dining out and recreational purchases."
+            )
+            
+    # 3. Dopamine triggers
+    if len(dopamine_txns) > 3:
+        insights.append(
+            f"🛍️ Dopamine Spending: Detected {len(dopamine_txns)} shopping spikes. "
+            "These purchases often occur in bursts, indicating reward-seeking behavior."
+        )
+        
+    # 4. Stress/Regret Spending
+    if len(stress_txns) > 0:
+        insights.append(
+            f"⚠️ Emotional Spending: You flagged {len(stress_txns)} transactions as 'regret' or 'stress spending'. "
+            "Implementing a 24-hour cooling-off rule for non-essential items over $100 could help."
+        )
+        
+    # General fallback if no major insights
+    if not insights:
+        insights.append("📊 Spending Discipline: Your transactions exhibit stable and regular timing, with minimal signs of emotional or impulsive spending.")
+
+    return {
+        "insights": insights,
+        "metrics": {
+            "late_night_count": len(late_night_txns),
+            "late_night_total": round(sum(t.amount for t in late_night_txns), 2),
+            "weekend_pct": round(weekend_pct, 2),
+            "impulsive_count": len(impulsive_txns),
+            "impulsive_total": round(sum(t.amount for t in impulsive_txns), 2),
+            "dopamine_count": len(dopamine_txns),
+            "stress_count": len(stress_txns),
+            "avg_transaction_amount": round(avg_txn, 2)
+        },
+        "category_breakdown": {cat: round(amt, 2) for cat, amt in category_totals.items()}
+    }

backend/app/ai/budget_planner.py

@@ -0,0 +1,303 @@
+"""
+Smart Budget Planner for BankBot
+Categorizes spending and provides budgeting insights
+"""
+
+import json
+import os
+import numpy as np
+import pandas as pd
+from datetime import datetime, timedelta
+from collections import defaultdict
+import uuid
+
+BUDGET_FILE = "budgets.json"
+
+# Category keywords for automatic categorization
+CATEGORY_KEYWORDS = {
+    "Food & Dining": ["restaurant", "food", "cafe", "pizza", "burger", "biryani", "zomato", "swiggy", "coffee", "tea", "meal"],
+    "Shopping": ["shop", "store", "mall", "amazon", "flipkart", "ebay", "retail", "boutique", "apparel", "clothes"],
+    "Travel": ["uber", "taxi", "bus", "flight", "train", "travel", "hotel", "airline", "booking", "transport"],
+    "Entertainment": ["movie", "cinema", "game", "netflix", "spotify", "music", "ticket", "concert", "show"],
+    "Bills & Utilities": ["electricity", "water", "gas", "internet", "mobile", "phone", "bill", "subscription"],
+    "Healthcare": ["hospital", "doctor", "pharmacy", "medical", "health", "clinic", "medicine"],
+    "Groceries": ["grocery", "supermarket", "vegetables", "fruits", "milk", "wheat", "bazar"],
+    "Fitness": ["gym", "yoga", "fitness", "sports", "training", "coach"],
+    "Insurance": ["insurance", "premium", "policy"],
+    "Education": ["school", "college", "course", "book", "tuition", "fees"],
+    "Loan & EMI": ["loan", "emi", "mortgage", "credit"],
+    "Transfer": ["transfer", "sent", "payment"]
+}
+
+class BudgetPlanner:
+    """Smart budget planning and expense tracking"""
+    
+    def __init__(self):
+        self.budgets = self.load_budgets()
+    
+    def load_budgets(self):
+        """Load saved budgets from file"""
+        if os.path.exists(BUDGET_FILE):
+            try:
+                with open(BUDGET_FILE, "r", encoding="utf-8") as f:
+                    return json.load(f)
+            except Exception as e:
+                print(f"Error loading budgets: {e}")
+                return {}
+        return {}
+    
+    def save_budgets(self):
+        """Save budgets to file"""
+        try:
+            with open(BUDGET_FILE, "w", encoding="utf-8") as f:
+                json.dump(self.budgets, f, indent=4, ensure_ascii=False)
+        except Exception as e:
+            print(f"Error saving budgets: {e}")
+    
+    def categorize_transaction(self, description, amount=0):
+        """
+        Automatically categorize a transaction based on description
+        Returns: Category name
+        """
+        description_lower = description.lower()
+        
+        # Check against keywords
+        for category, keywords in CATEGORY_KEYWORDS.items():
+            if any(keyword in description_lower for keyword in keywords):
+                return category
+        
+        # Default category
+        return "Other"
+    
+    def set_budget_limit(self, username, category, limit):
+        """Set budget limit for a spending category"""
+        if username not in self.budgets:
+            self.budgets[username] = {}
+        
+        self.budgets[username][category] = {
+            "limit": limit,
+            "created_at": datetime.now().isoformat(),
+            "alerts": []
+        }
+        self.save_budgets()
+    
+    def analyze_spending(self, username, transactions, period_days=30):
+        """
+        Analyze spending by category for a given period
+        Returns: Categorized spending data
+        """
+        if not transactions:
+            return {}
+        
+        # Filter transactions from last N days
+        cutoff_date = datetime.now() - timedelta(days=period_days)
+        recent_txns = []
+        
+        for txn in transactions:
+            try:
+                txn_date = datetime.fromisoformat(txn.get('date', ''))
+                if txn_date > cutoff_date and txn.get('type') == 'debit':
+                    recent_txns.append(txn)
+            except:
+                pass
+        
+        # Categorize transactions
+        spending_by_category = defaultdict(float)
+        categorized_txns = defaultdict(list)
+        
+        for txn in recent_txns:
+            category = self.categorize_transaction(
+                txn.get('description', txn.get('details', '')),
+                float(txn.get('amount', 0))
+            )
+            amount = float(txn.get('amount', 0))
+            spending_by_category[category] += amount
+            categorized_txns[category].append({
+                'date': txn.get('date'),
+                'amount': amount,
+                'details': txn.get('details', '')
+            })
+        
+        return {
+            "period_days": period_days,
+            "spending_by_category": dict(spending_by_category),
+            "categorized_transactions": dict(categorized_txns),
+            "total_spending": sum(spending_by_category.values()),
+            "transaction_count": len(recent_txns)
+        }
+    
+    def check_budget_alerts(self, username, spending_analysis):
+        """Check if any spending categories exceed their budgets"""
+        alerts = []
+        
+        if username not in self.budgets:
+            return alerts
+        
+        user_budgets = self.budgets.get(username, {})
+        spending = spending_analysis.get('spending_by_category', {})
+        
+        for category, budget_info in user_budgets.items():
+            if category not in spending:
+                continue
+            
+            spent = spending[category]
+            limit = budget_info.get('limit', 0)
+            
+            if spent > limit:
+                percentage = (spent / limit) * 100
+                alerts.append({
+                    "category": category,
+                    "spent": round(spent, 2),
+                    "limit": limit,
+                    "percentage": round(percentage, 1),
+                    "excess": round(spent - limit, 2),
+                    "severity": "high" if percentage > 150 else "medium" if percentage > 100 else "low",
+                    "timestamp": datetime.now().isoformat()
+                })
+        
+        return alerts
+    
+    def generate_budget_plan(self, username, transactions, monthly_income=50000):
+        """Generate recommended budget plan based on spending patterns"""
+        spending_analysis = self.analyze_spending(username, transactions, period_days=90)
+        spending = spending_analysis.get('spending_by_category', {})
+        
+        total_spending = spending_analysis.get('total_spending', 0)
+        avg_monthly_spending = total_spending / 3 if total_spending > 0 else 0
+        
+        # Calculate budget percentages (50/30/20 rule variant)
+        recommended_budgets = {}
+        
+        if spending:
+            for category, amount in spending.items():
+                percentage = (amount / total_spending * 100) if total_spending > 0 else 0
+                recommended_budget = (percentage / 100) * monthly_income
+                recommended_budgets[category] = round(recommended_budget, 2)
+        
+        # Add default categories if not present
+        default_categories = {
+            "Food & Dining": monthly_income * 0.08,
+            "Shopping": monthly_income * 0.10,
+            "Travel": monthly_income * 0.08,
+            "Bills & Utilities": monthly_income * 0.15,
+            "Entertainment": monthly_income * 0.05,
+            "Savings": monthly_income * 0.20,
+        }
+        
+        for category, amount in default_categories.items():
+            if category not in recommended_budgets:
+                recommended_budgets[category] = amount
+        
+        return {
+            "monthly_income": monthly_income,
+            "current_monthly_avg": round(avg_monthly_spending, 2),
+            "recommended_budgets": recommended_budgets,
+            "savings_potential": round(monthly_income - avg_monthly_spending, 2),
+            "budget_breakdown": {
+                "essentials": round(monthly_income * 0.50, 2),  # Bills, groceries, insurance
+                "lifestyle": round(monthly_income * 0.30, 2),   # Entertainment, dining, shopping
+                "savings": round(monthly_income * 0.20, 2)      # Emergency fund, investments
+            }
+        }
+    
+    def predict_monthly_spending(self, username, transactions):
+        """
+        Predict future spending using historical data
+        Returns: Predicted spending for next month
+        """
+        if not transactions:
+            return {}
+        
+        # Analyze last 3 months
+        predictions = {}
+        
+        for period in [30, 60, 90]:
+            analysis = self.analyze_spending(username, transactions, period_days=period)
+            spending = analysis.get('spending_by_category', {})
+            
+            # Calculate trends
+            for category, amount in spending.items():
+                if category not in predictions:
+                    predictions[category] = []
+                predictions[category].append(amount)
+        
+        # Calculate averages and trends
+        predicted_spending = {}
+        for category, amounts in predictions.items():
+            if amounts:
+                predicted_spending[category] = {
+                    "predicted": round(np.mean(amounts), 2),
+                    "trend": "increasing" if amounts[-1] > amounts[0] else "decreasing",
+                    "variance": round(np.std(amounts), 2)
+                }
+        
+        return predicted_spending
+    
+    def get_savings_suggestions(self, username, spending_analysis, monthly_income=50000):
+        """Generate specific savings suggestions"""
+        suggestions = []
+        spending = spending_analysis.get('spending_by_category', {})
+        
+        # Check each category and provide suggestions
+        for category, amount in spending.items():
+            percentage = (amount / monthly_income) * 100 if monthly_income > 0 else 0
+            
+            if category == "Food & Dining" and percentage > 10:
+                reduction = amount - (monthly_income * 0.08)
+                suggestions.append({
+                    "category": "Food & Dining",
+                    "potential_savings": round(reduction, 2),
+                    "suggestion": f"You can save ₹{round(reduction, 2)} by reducing dining expenses by 10%",
+                    "priority": "high" if reduction > 1000 else "medium"
+                })
+            
+            elif category == "Shopping" and percentage > 12:
+                reduction = amount - (monthly_income * 0.10)
+                suggestions.append({
+                    "category": "Shopping",
+                    "potential_savings": round(reduction, 2),
+                    "suggestion": f"Reduce impulse purchases to save ₹{round(reduction, 2)} monthly",
+                    "priority": "high" if reduction > 1000 else "medium"
+                })
+            
+            elif category == "Entertainment" and percentage > 7:
+                reduction = amount - (monthly_income * 0.05)
+                suggestions.append({
+                    "category": "Entertainment",
+                    "potential_savings": round(reduction, 2),
+                    "suggestion": f"Optimize subscriptions and entertainment to save ₹{round(reduction, 2)}",
+                    "priority": "low"
+                })
+        
+        # Overall savings tip
+        total_savings = sum(s.get('potential_savings', 0) for s in suggestions)
+        if total_savings > 0:
+            suggestions.append({
+                "category": "Total Potential Savings",
+                "potential_savings": round(total_savings, 2),
+                "suggestion": f"By following these suggestions, you can save ₹{round(total_savings, 2)} per month",
+                "priority": "high"
+            })
+        
+        return suggestions
+
+def get_budget_insights(username, transactions, users_data):
+    """Get comprehensive budget insights for a user"""
+    planner = BudgetPlanner()
+    
+    user_data = users_data.get(username, {})
+    monthly_income = user_data.get('monthly_income', 50000)
+    
+    spending_analysis = planner.analyze_spending(username, transactions)
+    budget_alerts = planner.check_budget_alerts(username, spending_analysis)
+    budget_plan = planner.generate_budget_plan(username, transactions, monthly_income)
+    savings_suggestions = planner.get_savings_suggestions(username, spending_analysis, monthly_income)
+    predicted_spending = planner.predict_monthly_spending(username, transactions)
+    
+    return {
+        "spending_analysis": spending_analysis,
+        "budget_alerts": budget_alerts,
+        "budget_plan": budget_plan,
+        "savings_suggestions": savings_suggestions,
+        "predicted_spending": predicted_spending
+    }

backend/app/ai/chat.py

@@ -0,0 +1,289 @@
+import json
+import os
+from threading import Lock
+from sqlalchemy.orm import Session
+from app.database.models import User, Account, Transaction, Goal, Investment, Subscription
+from app.ai.behavior import analyze_spending_behavior
+from app.ai.coaching import calculate_financial_health_score
+from app.ai.ollama_integration import get_groq_response, get_ollama_response, stream_groq_response, stream_ollama_response
+
+# Thread-safe chatbot memory storage
+class ChatMemoryManager:
+    def __init__(self):
+        self._history = {}
+        self._lock = Lock()
+
+    def get_history(self, user_id: str):
+        with self._lock:
+            if user_id not in self._history:
+                self._history[user_id] = []
+            return self._history[user_id]
+
+    def add_message(self, user_id: str, role: str, content: str):
+        with self._lock:
+            if user_id not in self._history:
+                self._history[user_id] = []
+            self._history[user_id].append({"role": role, "content": content})
+            # Limit history to last 12 messages (6 rounds)
+            if len(self._history[user_id]) > 12:
+                self._history[user_id] = self._history[user_id][-12:]
+
+    def clear_history(self, user_id: str):
+        with self._lock:
+            if user_id in self._history:
+                self._history[user_id] = []
+
+chat_memory = ChatMemoryManager()
+
+def build_user_context_string(db: Session, user_id: str) -> str:
+    """
+    Queries database for a user's entire financial situation to construct a precise system context.
+    """
+    user = db.query(User).filter(User.id == user_id).first()
+    if not user:
+        return "No user information available."
+        
+    accounts = db.query(Account).filter(Account.user_id == user_id).all()
+    total_balance = sum(acc.balance for acc in accounts)
+    account_details = [f"{acc.type.capitalize()} Account: ${acc.balance:,.2f}" for acc in accounts]
+    
+    goals = db.query(Goal).filter(Goal.user_id == user_id).all()
+    goals_details = [f"Goal '{g.title}': Target ${g.target_amount:,.2f}, Saved ${g.current_amount:,.2f}" for g in goals]
+    
+    investments = db.query(Investment).filter(Investment.user_id == user_id).all()
+    investments_details = [f"{i.asset_name} ({i.type}): invested ${i.amount_invested:,.2f}, Current Value ${i.current_value:,.2f}" for i in investments]
+    
+    subs = db.query(Subscription).filter(Subscription.user_id == user_id, Subscription.active == True).all()
+    subs_details = [f"{s.merchant}: ${s.amount:,.2f}/{s.billing_cycle}" for s in subs]
+    
+    # Run behavioral diagnostics
+    behavior = analyze_spending_behavior(db, user_id)
+    behavior_insights = behavior.get("insights", [])
+    
+    # Financial Score
+    score_data = calculate_financial_health_score(db, user_id)
+    financial_score = score_data.get("overall_score", 50)
+    
+    context = f"""
+    User Profile:
+    - Name: {user.profile_data.get('name', 'Client')}
+    - Financial Personality: {user.financial_personality}
+    - Financial Health Score: {financial_score:.0f}/100
+    
+    Balances:
+    {', '.join(account_details) if account_details else 'No active bank accounts'}
+    - Total Liquid Capital: ${total_balance:,.2f}
+    
+    Financial Goals:
+    {'; '.join(goals_details) if goals_details else 'None established'}
+    
+    Active Portfolio:
+    {'; '.join(investments_details) if investments_details else 'No active investments'}
+    
+    Active Subscriptions:
+    {'; '.join(subs_details) if subs_details else 'No active subscriptions'}
+    
+    Diagnostics & Behavior:
+    - {'; '.join(behavior_insights)}
+    - Late night spending occurrences: {behavior.get('metrics', {}).get('late_night_count', 0)}
+    - Weekend spending ratio: {behavior.get('metrics', {}).get('weekend_pct', 0.0)}%
+    """
+    return context
+
+def get_contextual_system_prompt(db: Session, user_id: str) -> str:
+    """
+    Constructs a highly specific system prompt containing the user's financial profile.
+    """
+    financial_context = build_user_context_string(db, user_id)
+    
+    system_prompt = f"""You are BankBot, an elite AI Financial Analyst, Wealth Advisor, and Predictive Banking Engine.
+    You communicate with the user, providing highly personalized, concise, and mathematically rigorous answers.
+    You have direct, read-only access to the client's current financial profile and database records.
+
+    CURRENT USER PORTFOLIO DATA:
+    {financial_context}
+
+    CORE PRINCIPLES:
+    1. NEVER behave like a generic chatbot. Avoid generic suggestions like "save more money". Use real numbers, calculate percentages, and suggest specific actions based on the client's data.
+    2. Respond with the authority and brevity of a Bloomberg Terminal analyst.
+    3. Keep your answers brief, actionable, and financially meaningful (typically 2-4 sentences max).
+    4. If the user asks a question about their spending, goals, or predictions, use the portfolio data above.
+    5. Always remain helpful, professional, and secure.
+    """
+    return system_prompt
+
+def get_offline_chat_fallback(db: Session, user_id: str, prompt: str) -> str:
+    """
+    Generates a localized, rule-grounded financial analyst reply when AI engines are offline.
+    """
+    user = db.query(User).filter(User.id == user_id).first()
+    persona = user.financial_personality if user else "Saver"
+    
+    prompt_lower = prompt.lower()
+    
+    if "discipline" in prompt_lower or "spend" in prompt_lower or "budget" in prompt_lower:
+        score_data = calculate_financial_health_score(db, user_id)
+        discipline_score = score_data.get("categories", {}).get("spending_discipline", {}).get("score", 10)
+        return (
+            f"As a {persona}, your spending discipline score stands at {discipline_score:.0f}/20. "
+            f"Analysis of your transaction history shows discretionary spikes. "
+            "To optimize your cashflow surplus, establish a strict 20% savings buffer prior to discretionary outflow."
+        )
+    elif "investment" in prompt_lower or "portfolio" in prompt_lower or "grow" in prompt_lower:
+        investments = db.query(Investment).filter(Investment.user_id == user_id).all()
+        inv_total = sum(i.current_value for i in investments)
+        return (
+            f"Your current investment portfolio valuation stands at ${inv_total:,.2f}. "
+            "Based on asset performance, shifting 15% of your net checking surplus into stock index funds "
+            "will counter inflation and capture a projected 8% compound annual return."
+        )
+    else:
+        score_data = calculate_financial_health_score(db, user_id)
+        score = score_data.get("overall_score", 50)
+        return (
+            f"Wealth Advisor assessment: Your overall Financial Health Score is {score:.0f}/100. "
+            "Liquidity is stable, but subscription and discretionary leakages are tempering compounding growth. "
+            "Audit duplicate subscriptions and automate goal savings to enhance your trajectory."
+        )
+
+def get_chat_response(db: Session, user_id: str, prompt: str) -> str:
+    """
+    Returns an HTTP conversational response grounded in database context.
+    """
+    from app.ai.ollama_integration import has_active_ai_backend
+    
+    if not has_active_ai_backend():
+        fallback_msg = get_offline_chat_fallback(db, user_id, prompt)
+        chat_memory.add_message(user_id, "user", prompt)
+        chat_memory.add_message(user_id, "assistant", fallback_msg)
+        return fallback_msg
+        
+    sys_prompt = get_contextual_system_prompt(db, user_id)
+    history = chat_memory.get_history(user_id)
+    
+    # Construct complete prompt for underlying backend
+    full_messages = [{"role": "system", "content": sys_prompt}]
+    for msg in history:
+        full_messages.append({"role": msg["role"], "content": msg["content"]})
+    full_messages.append({"role": "user", "content": prompt})
+    
+    # Determine backend
+    OPENAI_API_KEY = os.environ.get("OPENAI_API_KEY", "")
+    GROQ_API_KEY = os.environ.get("GROQ_API_KEY", "")
+    
+    response_content = None
+    
+    if OPENAI_API_KEY:
+        try:
+            from openai import OpenAI
+            client = OpenAI(api_key=OPENAI_API_KEY)
+            res = client.chat.completions.create(
+                model="gpt-4o-mini",
+                messages=full_messages,
+                temperature=0.1,
+                max_tokens=500
+            )
+            response_content = res.choices[0].message.content
+        except Exception as e:
+            print(f"OpenAI error in chat: {e}")
+            
+    if not response_content and GROQ_API_KEY:
+        try:
+            response_content = get_groq_response(prompt, history=history, language="English")
+        except Exception as e:
+            print(f"Groq error in chat: {e}")
+            
+    if not response_content:
+        # Fallback to local Ollama integration
+        try:
+            response_content = get_ollama_response(prompt, history=history, language="English")
+        except Exception as e:
+            print(f"Ollama error in chat: {e}")
+            
+    if not response_content:
+        response_content = get_offline_chat_fallback(db, user_id, prompt)
+        
+    # Save conversation
+    chat_memory.add_message(user_id, "user", prompt)
+    chat_memory.add_message(user_id, "assistant", response_content)
+    
+    return response_content
+
+def stream_chat_response(db: Session, user_id: str, prompt: str):
+    """
+    Generates streaming chunks for WebSocket or HTTP SSE.
+    """
+    from app.ai.ollama_integration import has_active_ai_backend
+    
+    if not has_active_ai_backend():
+        fallback_msg = get_offline_chat_fallback(db, user_id, prompt)
+        chat_memory.add_message(user_id, "user", prompt)
+        chat_memory.add_message(user_id, "assistant", fallback_msg)
+        # Yield words slowly to simulate streaming
+        import time
+        for word in fallback_msg.split(" "):
+            yield word + " "
+            time.sleep(0.05)
+        return
+        
+    sys_prompt = get_contextual_system_prompt(db, user_id)
+    history = chat_memory.get_history(user_id)
+    
+    full_messages = [{"role": "system", "content": sys_prompt}]
+    for msg in history:
+        full_messages.append({"role": msg["role"], "content": msg["content"]})
+    full_messages.append({"role": "user", "content": prompt})
+    
+    # Save user message to history
+    chat_memory.add_message(user_id, "user", prompt)
+    
+    OPENAI_API_KEY = os.environ.get("OPENAI_API_KEY", "")
+    GROQ_API_KEY = os.environ.get("GROQ_API_KEY", "")
+    
+    complete_reply = ""
+    
+    if OPENAI_API_KEY:
+        try:
+            from openai import OpenAI
+            client = OpenAI(api_key=OPENAI_API_KEY)
+            stream = client.chat.completions.create(
+                model="gpt-4o-mini",
+                messages=full_messages,
+                temperature=0.1,
+                max_tokens=500,
+                stream=True
+            )
+            for chunk in stream:
+                content = chunk.choices[0].delta.content
+                if content:
+                    complete_reply += content
+                    yield content
+            # Save assistant message once streaming completes
+            chat_memory.add_message(user_id, "assistant", complete_reply)
+            return
+        except Exception as e:
+            print(f"OpenAI streaming error: {e}")
+            
+    if GROQ_API_KEY:
+        try:
+            for chunk in stream_groq_response(prompt, history=history, language="English"):
+                if chunk:
+                    complete_reply += chunk
+                    yield chunk
+            chat_memory.add_message(user_id, "assistant", complete_reply)
+            return
+        except Exception as e:
+            print(f"Groq streaming error: {e}")
+            
+    # Fallback to local Ollama stream
+    try:
+        for chunk in stream_ollama_response(prompt, history=history, language="English"):
+            if chunk:
+                complete_reply += chunk
+                yield chunk
+        chat_memory.add_message(user_id, "assistant", complete_reply)
+    except Exception as e:
+        print(f"Ollama streaming error: {e}")
+        fallback_msg = get_offline_chat_fallback(db, user_id, prompt)
+        yield fallback_msg
+        chat_memory.add_message(user_id, "assistant", fallback_msg)

backend/app/ai/coaching.py

@@ -0,0 +1,244 @@
+import os
+from datetime import datetime, timedelta
+from sqlalchemy.orm import Session
+from app.database.models import User, Account, Transaction, Goal, Investment, Subscription
+from app.ai.forecasting import get_cashflow_metrics
+from app.ai.ollama_integration import get_ai_response
+
+def calculate_financial_health_score(db: Session, user_id: str):
+    """
+    Computes a multi-dimensional Financial Health Score (0-100) based on real database records.
+    """
+    accounts = db.query(Account).filter(Account.user_id == user_id).all()
+    total_balance = sum(acc.balance for acc in accounts)
+    savings_balance = sum(acc.balance for acc in accounts if acc.type.lower() == "savings")
+    
+    # Cashflow
+    current_balance, daily_income, daily_spending = get_cashflow_metrics(db, user_id)
+    monthly_income = max(1000.0, daily_income * 30.4)
+    monthly_spending = daily_spending * 30.4
+    
+    # 1. Savings Consistency (20 pts)
+    # Check frequency of saving transactions or goal additions
+    txns = db.query(Transaction).join(Account).filter(
+        Account.user_id == user_id,
+        Transaction.type == "credit",
+        Transaction.category == "Income"
+    ).count()
+    # Let's say if they have active goals with current_amount > 0, they get higher points
+    goals = db.query(Goal).filter(Goal.user_id == user_id).all()
+    goal_savings = sum(g.current_amount for g in goals)
+    
+    savings_score = 10.0
+    if goal_savings > 1000:
+        savings_score += 10.0
+    elif goal_savings > 0:
+        savings_score += 5.0
+        
+    # 2. Debt Ratio (20 pts)
+    # Estimate EMIs or goals with "debt"
+    debt_goals = sum(g.target_amount - g.current_amount for g in goals if "debt" in g.title.lower() or "loan" in g.title.lower())
+    # Standard monthly debt service (estimate 10% of debt or $150 minimum if debt exists)
+    est_monthly_debt = max(0.0, debt_goals * 0.05)
+    debt_to_income = est_monthly_debt / monthly_income
+    
+    debt_score = 20.0
+    if debt_to_income > 0.40:
+        debt_score = 5.0
+    elif debt_to_income > 0.20:
+        debt_score = 12.0
+    elif debt_to_income > 0.05:
+        debt_score = 18.0
+        
+    # 3. Spending Discipline (20 pts)
+    # Ratio of monthly spending to monthly income
+    savings_rate = (monthly_income - monthly_spending) / monthly_income if monthly_income > 0 else 0
+    discipline_score = 10.0
+    if savings_rate >= 0.30:
+        discipline_score = 20.0
+    elif savings_rate >= 0.15:
+        discipline_score = 16.0
+    elif savings_rate >= 0.0:
+        discipline_score = 12.0
+        
+    # 4. Emergency Fund (20 pts)
+    # Do they have 3-6 months of expenses in savings?
+    monthly_expenses = max(500.0, monthly_spending)
+    months_buffer = savings_balance / monthly_expenses
+    
+    emergency_score = 0.0
+    if months_buffer >= 6.0:
+        emergency_score = 20.0
+    elif months_buffer >= 3.0:
+        emergency_score = 15.0
+    elif months_buffer >= 1.0:
+        emergency_score = 8.0
+        
+    # 5. Investment Index (10 pts)
+    investments = db.query(Investment).filter(Investment.user_id == user_id).all()
+    inv_total = sum(i.current_value for i in investments)
+    
+    investment_score = 0.0
+    if inv_total > 5000:
+        investment_score = 10.0
+    elif inv_total > 0:
+        investment_score = 6.0
+        
+    # 6. Subscription Efficiency (10 pts)
+    subs = db.query(Subscription).filter(Subscription.user_id == user_id, Subscription.active == True).all()
+    sub_cost = sum(s.amount if s.billing_cycle.lower() == "monthly" else (s.amount / 12) for s in subs)
+    sub_ratio = sub_cost / monthly_income
+    
+    sub_score = 10.0
+    if sub_ratio > 0.10:  # More than 10% of income on subscriptions
+        sub_score = 3.0
+    elif sub_ratio > 0.05: # More than 5%
+        sub_score = 7.0
+        
+    # Calculate Overall Score
+    overall_score = savings_score + debt_score + discipline_score + emergency_score + investment_score + sub_score
+    overall_score = min(100.0, max(0.0, overall_score))
+    
+    # Actionable improvements list
+    improvements = []
+    if savings_score < 15:
+        improvements.append("Set up automated transfers to your Savings account right after payday.")
+    if debt_score < 15:
+        improvements.append("Prioritize high-interest debt payoffs using the debt avalanche method.")
+    if discipline_score < 15:
+        improvements.append("Discretionary spending (shopping & dining) is high. Try implementing a $50 weekly limit.")
+    if emergency_score < 15:
+        improvements.append(f"Build savings buffer. Try to accumulate at least ${monthly_expenses * 3:,.2f} (3 months of expenses).")
+    if investment_score < 6:
+        improvements.append("Start a low-cost stock index fund SIP to counter inflation.")
+    if sub_score < 8:
+        improvements.append("Conduct an audit of active subscriptions. Cancel duplicate/unused memberships.")
+        
+    if not improvements:
+        improvements.append("Maintain your current financial habits; your portfolio is highly optimized!")
+        
+    # AI Explanation
+    user = db.query(User).filter(User.id == user_id).first()
+    persona = user.financial_personality if user else "Saver"
+    
+    ai_prompt = f"""
+    The user is a '{persona}' with a Financial Health Score of {overall_score:.0f}/100.
+    Sub-scores:
+    - Savings Consistency: {savings_score:.0f}/20
+    - Debt Management: {debt_score:.0f}/20
+    - Spending Discipline: {discipline_score:.0f}/20
+    - Emergency Fund: {emergency_score:.0f}/20
+    - Investment Allocation: {investment_score:.0f}/10
+    - Subscription Management: {sub_score:.0f}/10
+    
+    Write a concise, professional financial analyst explanation of this score. Detail the primary strengths and key weaknesses.
+    Do NOT write a generic chatbot reply. Keep it to 3-4 sentences. Format like a Bloomberg analyst report.
+    """
+    
+    from app.ai.ollama_integration import has_active_ai_backend
+    
+    explanation = None
+    if has_active_ai_backend():
+        try:
+            # Hard 8-second timeout so the health score endpoint never hangs
+            import threading
+            result = [None]
+            def _call():
+                result[0] = get_ai_response(ai_prompt)
+            t = threading.Thread(target=_call, daemon=True)
+            t.start()
+            t.join(timeout=8)
+            explanation = result[0]
+        except Exception:
+            pass
+            
+    if not explanation:
+        explanation = f"As a {persona}, your financial health score of {overall_score:.0f} reflects solid fundamentals with opportunities to optimize emergency allocations and subscription efficiencies. Focus on automating savings and expanding investments."
+        
+    return {
+        "overall_score": round(overall_score, 0),
+        "categories": {
+            "savings_consistency": {"score": round(savings_score, 0), "max": 20},
+            "debt_ratio": {"score": round(debt_score, 0), "max": 20},
+            "spending_discipline": {"score": round(discipline_score, 0), "max": 20},
+            "emergency_funds": {"score": round(emergency_score, 0), "max": 20},
+            "investments": {"score": round(investment_score, 0), "max": 10},
+            "subscription_management": {"score": round(sub_score, 0), "max": 10}
+        },
+        "explanation": explanation,
+        "actionable_improvements": improvements
+    }
+
+def generate_daily_briefing(db: Session, user_id: str):
+    """
+    Pulls complete financial context and generates a personalized daily financial briefing.
+    """
+    user = db.query(User).filter(User.id == user_id).first()
+    if not user:
+        return {"briefing": "User not found."}
+        
+    # Collect data
+    accounts = db.query(Account).filter(Account.user_id == user_id).all()
+    total_balance = sum(acc.balance for acc in accounts)
+    
+    goals = db.query(Goal).filter(Goal.user_id == user_id).all()
+    goals_summary = [f"{g.title}: {g.current_amount}/{g.target_amount}" for g in goals]
+    
+    investments = db.query(Investment).filter(Investment.user_id == user_id).all()
+    inv_summary = [f"{i.asset_name} ({i.type}): Current Value ${i.current_value:,.2f}" for i in investments]
+    
+    # Cashflow
+    current_balance, daily_income, daily_spending = get_cashflow_metrics(db, user_id)
+    monthly_income = daily_income * 30.4
+    monthly_spending = daily_spending * 30.4
+    
+    # Format AI Prompt
+    ai_prompt = f"""
+    You are an AI Wealth Advisor and Predictive Banking Engine. Generate a personalized daily financial briefing for {user.profile_data.get('name', 'User')}.
+    
+    Financial Summary:
+    - User Personality: {user.financial_personality}
+    - Total Account Balance: ${total_balance:,.2f}
+    - Estimated Monthly Income: ${monthly_income:,.2f}
+    - Estimated Monthly Spending: ${monthly_spending:,.2f}
+    - Active Goals: {', '.join(goals_summary) if goals_summary else 'None'}
+    - Investments: {', '.join(inv_summary) if inv_summary else 'None'}
+    
+    Generate a 3-paragraph daily briefing.
+    Paragraph 1: Summary of their current liquidity and portfolio health.
+    Paragraph 2: One specific recommendation regarding their savings goals or investment potential.
+    Paragraph 3: A behavioral spending insight warning based on their spending velocity.
+    
+    Style: Bloomberg Terminal style, highly intelligent, concise, financially meaningful, human-like.
+    Avoid boilerplate generic remarks (e.g. 'You should try saving more money'). Use exact figures.
+    """
+    
+    from app.ai.ollama_integration import has_active_ai_backend
+    
+    briefing = None
+    if has_active_ai_backend():
+        try:
+            import threading
+            result = [None]
+            def _call():
+                result[0] = get_ai_response(ai_prompt)
+            t = threading.Thread(target=_call, daemon=True)
+            t.start()
+            t.join(timeout=10)
+            briefing = result[0]
+        except Exception:
+            pass
+            
+    if not briefing:
+        briefing = f"DAILY BRIEFING:\n\nYour liquid capital stands at ${total_balance:,.2f}. Portfolio indicators suggest regular cashflow velocity. Based on your {user.financial_personality} profile, we advise dedicating a portion of your net surplus to your active goals to optimize compound growth. Avoid non-essential weekend dining and retail spikes to maintain your target trajectory."
+        
+    return {
+        "date": datetime.utcnow().strftime("%Y-%m-%d"),
+        "user_name": user.profile_data.get('name', 'User'),
+        "briefing": briefing,
+        "metrics": {
+            "total_liquid_capital": round(total_balance, 2),
+            "monthly_income_projection": round(monthly_income, 2),
+            "monthly_burn_rate": round(monthly_spending, 2)
+        }
+    }

backend/app/ai/forecasting.py

@@ -0,0 +1,182 @@
+from datetime import datetime, timedelta
+import numpy as np
+from sqlalchemy.orm import Session
+from app.database.models import Account, Transaction, Goal, Investment, Subscription
+
+def get_cashflow_metrics(db: Session, user_id: str, days: int = 90):
+    """
+    Computes daily average income and spending based on historical transactions.
+    """
+    # Fetch checking & savings accounts for user
+    accounts = db.query(Account).filter(Account.user_id == user_id).all()
+    account_ids = [acc.id for acc in accounts]
+    
+    if not account_ids:
+        return 0.0, 0.0, 0.0  # Current balance, avg daily income, avg daily spending
+        
+    current_balance = sum(acc.balance for acc in accounts)
+    
+    # Fetch recent transactions
+    cutoff = datetime.utcnow() - timedelta(days=days)
+    txns = db.query(Transaction).filter(
+        Transaction.account_id.in_(account_ids),
+        Transaction.timestamp >= cutoff
+    ).all()
+    
+    if not txns:
+        return current_balance, 0.0, 0.0
+        
+    total_income = sum(t.amount for t in txns if t.type.lower() == "credit")
+    total_spending = sum(t.amount for t in txns if t.type.lower() == "debit")
+    
+    avg_daily_income = total_income / days
+    avg_daily_spending = total_spending / days
+    
+    return current_balance, avg_daily_income, avg_daily_spending
+
+def predict_future_balance(db: Session, user_id: str, projection_days: int = 90):
+    """
+    Predicts future balances and returns trend description.
+    """
+    current_balance, daily_income, daily_spending = get_cashflow_metrics(db, user_id)
+    
+    net_daily = daily_income - daily_spending
+    projected_balance = max(0.0, current_balance + (net_daily * projection_days))
+    
+    # Calculate percentage change
+    if current_balance > 0:
+        percent_change = (projected_balance - current_balance) / current_balance * 100
+    else:
+        percent_change = 0.0
+        
+    # Generate human-friendly description
+    if percent_change < 0:
+        insight = f"If current spending continues, your total balance may decrease by {abs(percent_change):.1f}% (down to ${projected_balance:,.2f}) in {projection_days} days."
+    elif percent_change > 0:
+        insight = f"Based on current trends, your total balance is projected to grow by {percent_change:.1f}% (up to ${projected_balance:,.2f}) in {projection_days} days."
+    else:
+        insight = "Your financial trajectory is steady with minor balance fluctuations."
+        
+    # Generate daily data points for charts
+    chart_data = []
+    for day in range(0, projection_days + 1, 5):
+        val = max(0.0, current_balance + (net_daily * day))
+        date_str = (datetime.utcnow() + timedelta(days=day)).strftime("%Y-%m-%d")
+        chart_data.append({"date": date_str, "balance": round(val, 2)})
+        
+    return {
+        "current_balance": round(current_balance, 2),
+        "projected_balance": round(projected_balance, 2),
+        "percent_change": round(percent_change, 2),
+        "net_daily": round(net_daily, 2),
+        "insight": insight,
+        "chart_data": chart_data
+    }
+
+def forecast_savings_and_investments(db: Session, user_id: str, projection_months: int = 12):
+    """
+    Projects savings and investment growth.
+    """
+    accounts = db.query(Account).filter(Account.user_id == user_id).all()
+    savings_balance = sum(acc.balance for acc in accounts if acc.type.lower() == "savings")
+    checking_balance = sum(acc.balance for acc in accounts if acc.type.lower() == "checking")
+    
+    investments = db.query(Investment).filter(Investment.user_id == user_id).all()
+    total_invested = sum(inv.current_value for inv in investments)
+    
+    # Subscriptions and recurring bills
+    subs = db.query(Subscription).filter(Subscription.user_id == user_id, Subscription.active == True).all()
+    monthly_sub_cost = sum(sub.amount if sub.billing_cycle.lower() == "monthly" else (sub.amount / 12) for sub in subs)
+    
+    # Let's assume standard default rates if not specified
+    savings_apr = 0.04  # 4% APY
+    investment_apr = 0.08  # 8% APY
+    
+    # We assume the user saves 10% of their net income monthly (derived from transaction history)
+    _, daily_income, daily_spending = get_cashflow_metrics(db, user_id)
+    monthly_income = daily_income * 30.4
+    monthly_spending = daily_spending * 30.4
+    net_monthly = max(0.0, monthly_income - monthly_spending)
+    monthly_savings_addition = net_monthly * 0.5  # Put 50% of net into savings
+    monthly_investment_addition = net_monthly * 0.3  # Put 30% of net into investments
+    
+    savings_data = []
+    investment_data = []
+    debt_data = []
+    
+    current_savings = savings_balance
+    current_inv = total_invested
+    
+    # Let's model a baseline debt if the user has a Goal of type "debt" or a general dummy debt
+    # We will look for Goals containing "debt" or "loan"
+    goals = db.query(Goal).filter(Goal.user_id == user_id).all()
+    debt_goal = next((g for g in goals if "debt" in g.title.lower() or "loan" in g.title.lower()), None)
+    
+    total_debt = 5000.0  # Default initial simulated debt if none found
+    if debt_goal:
+        total_debt = max(0.0, debt_goal.target_amount - debt_goal.current_amount)
+    
+    monthly_debt_payment = min(total_debt, max(150.0, net_monthly * 0.1)) # Assume 10% of net or at least $150
+    
+    for month in range(0, projection_months + 1):
+        # Compounding savings
+        if month > 0:
+            current_savings = (current_savings + monthly_savings_addition) * (1 + savings_apr / 12)
+            current_inv = (current_inv + monthly_investment_addition) * (1 + investment_apr / 12)
+            total_debt = max(0.0, total_debt - monthly_debt_payment)
+            
+        label = f"Month {month}"
+        savings_data.append({"month": label, "amount": round(current_savings, 2)})
+        investment_data.append({"month": label, "amount": round(current_inv, 2)})
+        debt_data.append({"month": label, "amount": round(total_debt, 2)})
+        
+    return {
+        "projection_months": projection_months,
+        "monthly_savings_addition": round(monthly_savings_addition, 2),
+        "monthly_investment_addition": round(monthly_investment_addition, 2),
+        "savings_growth": savings_data,
+        "investment_growth": investment_data,
+        "debt_decline": debt_data,
+        "total_projected_savings": round(current_savings, 2),
+        "total_projected_investments": round(current_inv, 2),
+        "total_remaining_debt": round(total_debt, 2)
+    }
+
+def simulate_future_scenarios(db: Session, user_id: str, projection_months: int = 6):
+    """
+    Simulates three scenarios: Status Quo, Frugal (cut spending 20%), and Luxury (increase spending 15%).
+    """
+    current_balance, daily_income, daily_spending = get_cashflow_metrics(db, user_id)
+    monthly_income = daily_income * 30.4
+    monthly_spending = daily_spending * 30.4
+    
+    scenarios = {
+        "status_quo": {"spend_mult": 1.0, "name": "Status Quo (Current spending)"},
+        "frugal": {"spend_mult": 0.8, "name": "Frugal Mode (Cut non-essentials by 20%)"},
+        "lifestyle_inflation": {"spend_mult": 1.15, "name": "Lifestyle Inflation (+15% spending)"}
+    }
+    
+    results = {}
+    for key, config in scenarios.items():
+        mult = config["spend_mult"]
+        projected_spend = monthly_spending * mult
+        net_monthly = monthly_income - projected_spend
+        
+        balance_trend = []
+        balance = current_balance
+        for m in range(0, projection_months + 1):
+            if m > 0:
+                balance = max(0.0, balance + net_monthly)
+            balance_trend.append({"month": f"M{m}", "balance": round(balance, 2)})
+            
+        results[key] = {
+            "name": config["name"],
+            "monthly_income": round(monthly_income, 2),
+            "monthly_spending": round(projected_spend, 2),
+            "net_monthly": round(net_monthly, 2),
+            "balance_projection": balance_trend,
+            "final_balance": round(balance, 2),
+            "savings_change_pct": round(((balance - current_balance) / current_balance * 100) if current_balance > 0 else 0.0, 2)
+        }
+        
+    return results

backend/app/ai/fraud.py

@@ -0,0 +1,123 @@
+from datetime import datetime, timedelta
+import numpy as np
+from sqlalchemy.orm import Session
+from app.database.models import Transaction, FraudLog, Account, User
+
+def evaluate_transaction_for_fraud(db: Session, transaction_id: str):
+    """
+    Evaluates a transaction for anomalies, generates a score, and logs alerts.
+    """
+    txn = db.query(Transaction).filter(Transaction.id == transaction_id).first()
+    if not txn:
+        return {"error": "Transaction not found"}
+        
+    account = db.query(Account).filter(Account.id == txn.account_id).first()
+    if not account:
+        return {"error": "Account not found for transaction"}
+        
+    user_id = account.user_id
+    
+    # Fetch historical transactions to compare
+    history = db.query(Transaction).join(Account).filter(
+        Account.user_id == user_id,
+        Transaction.type == "debit",
+        Transaction.id != transaction_id
+    ).order_by(Transaction.timestamp.desc()).limit(30).all()
+    
+    score = 0
+    reasons = []
+    
+    # 1. Spikes in amount
+    if history:
+        amounts = [h.amount for h in history]
+        avg_amount = np.mean(amounts)
+        std_amount = np.std(amounts) if len(amounts) > 1 else 0.0
+        
+        if txn.amount > avg_amount * 3.5:
+            score += 40
+            reasons.append(f"Transaction amount (${txn.amount:,.2f}) is abnormally high compared to your historical average of ${avg_amount:,.2f}.")
+        elif txn.amount > avg_amount * 2.0:
+            score += 20
+            reasons.append(f"Transaction amount is significantly higher than usual (2x historical average).")
+    else:
+        avg_amount = 0.0
+        
+    # 2. Timing anomaly (Late night 11 PM - 4 AM)
+    hour = txn.timestamp.hour
+    if hour >= 23 or hour < 4:
+        score += 25
+        reasons.append("Unusual timing (transaction placed between 11 PM and 4 AM).")
+        
+    # 3. Frequency anomaly (rapid consecutive transactions)
+    if history:
+        latest_txn = history[0]
+        time_diff = abs((txn.timestamp - latest_txn.timestamp).total_seconds())
+        if time_diff < 180:  # Less than 3 minutes
+            score += 20
+            reasons.append("High-frequency activity: multiple transactions placed within 3 minutes.")
+            
+    # 4. Duplicate transaction check (same merchant and amount within 10 minutes)
+    if history:
+        for prev in history[:5]:
+            time_diff = abs((txn.timestamp - prev.timestamp).total_seconds())
+            if prev.merchant == txn.merchant and prev.amount == txn.amount and time_diff < 600:
+                score += 30
+                reasons.append(f"Potential duplicate payment: identical debit of ${txn.amount:.2f} at {txn.merchant} detected within 10 minutes.")
+                break
+                
+    # Normalize score to 100 max
+    score = min(100, score)
+    
+    # Log to DB if score exceeds threshold
+    if score >= 30:
+        # Check if fraud log already exists
+        existing_log = db.query(FraudLog).filter(FraudLog.transaction_id == txn.id).first()
+        if not existing_log:
+            fraud_log = FraudLog(
+                transaction_id=txn.id,
+                risk_score=score / 100.0,
+                suspicious_activity_details="; ".join(reasons),
+                status="pending"
+            )
+            db.add(fraud_log)
+            db.commit()
+            
+    return {
+        "transaction_id": txn.id,
+        "amount": txn.amount,
+        "merchant": txn.merchant,
+        "timestamp": txn.timestamp.isoformat(),
+        "fraud_risk_score": score,
+        "is_anomalous": score >= 30,
+        "explanations": reasons,
+        "status": "flagged" if score >= 50 else "suspicious" if score >= 30 else "verified"
+    }
+
+def get_user_fraud_alerts(db: Session, user_id: str):
+    """
+    Retrieves all flagged/suspicious transaction records and logs.
+    """
+    logs = db.query(FraudLog).join(Transaction).join(Account).filter(
+        Account.user_id == user_id
+    ).order_by(Transaction.timestamp.desc()).all()
+    
+    alerts = []
+    for log in logs:
+        txn = log.transaction
+        alerts.append({
+            "fraud_log_id": log.id,
+            "transaction_id": txn.id,
+            "amount": txn.amount,
+            "merchant": txn.merchant,
+            "category": txn.category,
+            "timestamp": txn.timestamp.isoformat(),
+            "risk_score": round(log.risk_score * 100, 0),
+            "details": log.suspicious_activity_details,
+            "status": log.status
+        })
+        
+    return {
+        "total_alerts": len(alerts),
+        "pending_reviews": sum(1 for a in alerts if a["status"] == "pending"),
+        "alerts": alerts
+    }

backend/app/ai/fraud_detection.py

@@ -0,0 +1,286 @@
+"""
+AI Fraud Detection System for BankBot
+Uses machine learning to detect suspicious transactions
+"""
+
+import json
+import os
+import numpy as np
+import pandas as pd
+from datetime import datetime, timedelta
+from sklearn.ensemble import IsolationForest, RandomForestClassifier
+from sklearn.preprocessing import StandardScaler
+import pickle
+import uuid
+
+FRAUD_ALERTS_FILE = "fraud_alerts.json"
+FRAUD_MODEL_FILE = "fraud_model.pkl"
+
+class FraudDetectionEngine:
+    """Advanced fraud detection using multiple ML algorithms"""
+    
+    def __init__(self):
+        self.isolation_forest = None
+        self.scaler = StandardScaler()
+        self.load_model()
+    
+    def load_model(self):
+        """Load saved model or create new one"""
+        if os.path.exists(FRAUD_MODEL_FILE):
+            try:
+                with open(FRAUD_MODEL_FILE, "rb") as f:
+                    model_data = pickle.load(f)
+                    self.isolation_forest = model_data.get("model")
+                    self.scaler = model_data.get("scaler", StandardScaler())
+            except Exception as e:
+                print(f"Error loading fraud model: {e}")
+                self._initialize_model()
+        else:
+            self._initialize_model()
+    
+    def _initialize_model(self):
+        """Initialize Isolation Forest for anomaly detection"""
+        self.isolation_forest = IsolationForest(
+            contamination=0.1,  # Expect ~10% anomalies
+            random_state=42,
+            n_estimators=100
+        )
+    
+    def save_model(self):
+        """Save trained model to disk"""
+        try:
+            with open(FRAUD_MODEL_FILE, "wb") as f:
+                pickle.dump({
+                    "model": self.isolation_forest,
+                    "scaler": self.scaler
+                }, f)
+        except Exception as e:
+            print(f"Error saving fraud model: {e}")
+    
+    def extract_features(self, transactions):
+        """
+        Extract numerical features from transaction history
+        Returns: DataFrame with features for ML model
+        """
+        if not transactions or len(transactions) < 2:
+            return None
+        
+        df = pd.DataFrame(transactions)
+        
+        # Convert date strings to datetime
+        df['date'] = pd.to_datetime(df['date'], errors='coerce')
+        
+        features = []
+        for txn in transactions:
+            try:
+                amount = float(txn.get('amount', 0))
+                txn_type = 1 if txn.get('type') == 'debit' else 0
+                
+                feature_dict = {
+                    'amount': amount,
+                    'type': txn_type,
+                    'hour': datetime.fromisoformat(txn.get('date', '')).hour if txn.get('date') else 12,
+                    'day_of_week': datetime.fromisoformat(txn.get('date', '')).weekday() if txn.get('date') else 3,
+                }
+                features.append(feature_dict)
+            except Exception as e:
+                print(f"Error extracting features: {e}")
+                continue
+        
+        return pd.DataFrame(features) if features else None
+    
+    def detect_anomalies(self, transactions):
+        """
+        Detect anomalous transactions using Isolation Forest
+        Returns: List of anomaly indices and scores
+        """
+        if not transactions or len(transactions) < 2:
+            return [], []
+        
+        features_df = self.extract_features(transactions)
+        if features_df is None or len(features_df) < 2:
+            return [], []
+        
+        try:
+            # Normalize features
+            X = self.scaler.fit_transform(features_df)
+            
+            # Detect anomalies (-1 = anomaly, 1 = normal)
+            predictions = self.isolation_forest.predict(X)
+            anomaly_scores = self.isolation_forest.score_samples(X)
+            
+            # Find anomalies
+            anomalies = np.where(predictions == -1)[0].tolist()
+            
+            return anomalies, anomaly_scores
+        except Exception as e:
+            print(f"Error in anomaly detection: {e}")
+            return [], []
+    
+    def calculate_fraud_score(self, transaction, user_history):
+        """
+        Calculate fraud probability for a single transaction (0-100)
+        Considers: amount, frequency, location, time patterns
+        """
+        score = 0
+        reasons = []
+        
+        try:
+            amount = float(transaction.get('amount', 0))
+            
+            # Rule 1: Large withdrawal
+            avg_transaction = np.mean([float(t.get('amount', 0)) 
+                                      for t in user_history[-20:] if t.get('type') == 'debit'])
+            if avg_transaction > 0 and amount > avg_transaction * 3:
+                score += 25
+                reasons.append("Unusually large transaction")
+            
+            # Rule 2: Rapid consecutive transactions (within 5 minutes)
+            if len(user_history) > 1:
+                last_txn_time = datetime.fromisoformat(user_history[0].get('date', ''))
+                current_time = datetime.fromisoformat(transaction.get('date', ''))
+                if (current_time - last_txn_time).total_seconds() < 300:
+                    score += 20
+                    reasons.append("Rapid consecutive transactions")
+            
+            # Rule 3: Late night transaction (11 PM - 4 AM)
+            try:
+                hour = datetime.fromisoformat(transaction.get('date', '')).hour
+                if hour >= 23 or hour < 4:
+                    score += 15
+                    reasons.append("Unusual time of transaction")
+            except:
+                pass
+            
+            # Rule 4: Weekend large transaction
+            try:
+                day = datetime.fromisoformat(transaction.get('date', '')).weekday()
+                if day >= 5 and amount > avg_transaction * 2:  # Saturday/Sunday
+                    score += 10
+                    reasons.append("Weekend large transaction")
+            except:
+                pass
+            
+            # Rule 5: Debit after multiple recent debits
+            debit_count = sum(1 for t in user_history[-5:] if t.get('type') == 'debit')
+            if debit_count >= 4:
+                score += 15
+                reasons.append("Multiple recent debits")
+            
+            # Cap score at 100
+            score = min(score, 100)
+            
+        except Exception as e:
+            print(f"Error calculating fraud score: {e}")
+        
+        return score, reasons
+
+def check_fraud_alerts(username, users_data):
+    """
+    Check for fraud alerts for a user
+    Returns: List of fraud alerts
+    """
+    user_data = users_data.get(username, {})
+    transactions = user_data.get('transactions', [])
+    
+    if not transactions:
+        return []
+    
+    detector = FraudDetectionEngine()
+    alerts = []
+    
+    try:
+        # Analyze recent transactions (last 10)
+        recent_txns = transactions[:10]
+        anomalies, scores = detector.detect_anomalies(recent_txns)
+        
+        # Create alerts for anomalies
+        for idx in anomalies:
+            if idx < len(recent_txns):
+                txn = recent_txns[idx]
+                fraud_score, reasons = detector.calculate_fraud_score(txn, recent_txns)
+                
+                if fraud_score > 30:  # Alert threshold
+                    alert = {
+                        "id": str(uuid.uuid4()),
+                        "transaction_id": txn.get('id'),
+                        "amount": txn.get('amount'),
+                        "fraud_score": fraud_score,
+                        "reasons": reasons,
+                        "timestamp": datetime.now().isoformat(),
+                        "status": "active"
+                    }
+                    alerts.append(alert)
+    
+    except Exception as e:
+        print(f"Error checking fraud alerts: {e}")
+    
+    return alerts
+
+def get_fraud_alerts_summary(username, users_data):
+    """Get summary of fraud alerts for a user"""
+    alerts = check_fraud_alerts(username, users_data)
+    
+    high_risk = sum(1 for a in alerts if a.get('fraud_score', 0) > 70)
+    medium_risk = sum(1 for a in alerts if 30 < a.get('fraud_score', 0) <= 70)
+    
+    return {
+        "total_alerts": len(alerts),
+        "high_risk": high_risk,
+        "medium_risk": medium_risk,
+        "alerts": alerts[:5]  # Return latest 5
+    }
+
+def generate_fraud_report(username, users_data, days=30):
+    """Generate a comprehensive fraud analysis report"""
+    user_data = users_data.get(username, {})
+    transactions = user_data.get('transactions', [])
+    
+    if not transactions:
+        return None
+    
+    # Filter transactions from last N days
+    cutoff_date = datetime.now() - timedelta(days=days)
+    recent_txns = [t for t in transactions 
+                   if datetime.fromisoformat(t.get('date', '')) > cutoff_date]
+    
+    detector = FraudDetectionEngine()
+    
+    # Calculate statistics
+    total_transactions = len(recent_txns)
+    total_debit = sum(float(t.get('amount', 0)) for t in recent_txns if t.get('type') == 'debit')
+    avg_transaction = total_debit / len([t for t in recent_txns if t.get('type') == 'debit']) if any(t.get('type') == 'debit' for t in recent_txns) else 0
+    
+    # Run anomaly detection
+    anomalies, _ = detector.detect_anomalies(recent_txns)
+    
+    report = {
+        "period_days": days,
+        "total_transactions": total_transactions,
+        "total_debit_amount": total_debit,
+        "average_transaction": round(avg_transaction, 2),
+        "anomalies_detected": len(anomalies),
+        "risk_level": "HIGH" if len(anomalies) > total_transactions * 0.15 else "MEDIUM" if len(anomalies) > total_transactions * 0.05 else "LOW",
+        "alerts": check_fraud_alerts(username, users_data),
+        "recommendations": generate_fraud_recommendations(username, users_data)
+    }
+    
+    return report
+
+def generate_fraud_recommendations(username, users_data):
+    """Generate recommendations based on fraud analysis"""
+    alerts = check_fraud_alerts(username, users_data)
+    recommendations = []
+    
+    if not alerts:
+        recommendations.append("✅ No suspicious activities detected. Your account is secure.")
+    else:
+        high_risk_count = sum(1 for a in alerts if a.get('fraud_score', 0) > 70)
+        if high_risk_count > 0:
+            recommendations.append(f"⚠️ {high_risk_count} high-risk transactions detected. Please verify them immediately.")
+        
+        recommendations.append("💡 Enable transaction alerts for amounts above ₹5,000")
+        recommendations.append("🔐 Review and update your password regularly")
+        recommendations.append("📱 Use 2FA for additional security")
+    
+    return recommendations

backend/app/ai/loan_prediction_model.pkl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:17a92ade8661126d286434ab96256939040736511018f552b2a2b78156a5377f
+size 55529

backend/app/ai/loan_predictor.py

@@ -0,0 +1,301 @@
+"""
+AI Loan Eligibility Predictor for BankBot
+Predicts loan approval chance and EMI affordability using ML
+"""
+
+import numpy as np
+import pandas as pd
+from sklearn.preprocessing import StandardScaler
+from sklearn.ensemble import RandomForestClassifier, GradientBoostingClassifier
+import pickle
+import os
+from datetime import datetime
+import json
+
+LOAN_MODEL_FILE = "loan_prediction_model.pkl"
+
+class LoanEligibilityPredictor:
+    """ML-based loan eligibility prediction"""
+    
+    def __init__(self):
+        self.classifier = None
+        self.scaler = StandardScaler()
+        self.feature_names = [
+            'salary', 'credit_score', 'existing_loans', 
+            'employment_years', 'age', 'loan_amount'
+        ]
+        self.load_model()
+    
+    def load_model(self):
+        """Load saved model or create new one"""
+        if os.path.exists(LOAN_MODEL_FILE):
+            try:
+                with open(LOAN_MODEL_FILE, "rb") as f:
+                    model_data = pickle.load(f)
+                    self.classifier = model_data.get("classifier")
+                    self.scaler = model_data.get("scaler", StandardScaler())
+            except Exception as e:
+                print(f"Error loading loan model: {e}")
+                self._initialize_model()
+        else:
+            self._initialize_model()
+    
+    def _initialize_model(self):
+        """Initialize Random Forest for loan prediction"""
+        # Create synthetic training data
+        X_train = np.array([
+            [100000, 750, 0, 5, 35, 500000],      # Approved
+            [150000, 800, 1, 10, 42, 1000000],    # Approved
+            [200000, 780, 2, 8, 45, 1500000],     # Approved
+            [50000, 600, 3, 2, 28, 300000],       # Rejected
+            [80000, 650, 2, 3, 32, 400000],       # Rejected
+            [120000, 700, 1, 6, 38, 600000],      # Approved
+            [45000, 580, 4, 1, 25, 250000],       # Rejected
+            [180000, 770, 0, 12, 50, 900000],     # Approved
+            [70000, 620, 3, 2, 30, 350000],       # Rejected
+            [160000, 790, 1, 9, 44, 800000],      # Approved
+        ])
+        
+        y_train = np.array([1, 1, 1, 0, 0, 1, 0, 1, 0, 1])  # 1=Approved, 0=Rejected
+        
+        # Normalize features
+        X_train_scaled = self.scaler.fit_transform(X_train)
+        
+        # Train classifier
+        self.classifier = RandomForestClassifier(n_estimators=100, random_state=42)
+        self.classifier.fit(X_train_scaled, y_train)
+        
+        self.save_model()
+    
+    def save_model(self):
+        """Save trained model to disk"""
+        try:
+            with open(LOAN_MODEL_FILE, "wb") as f:
+                pickle.dump({
+                    "classifier": self.classifier,
+                    "scaler": self.scaler
+                }, f)
+        except Exception as e:
+            print(f"Error saving loan model: {e}")
+    
+    def predict_eligibility(self, salary, credit_score, existing_loans, 
+                           employment_years, age, loan_amount):
+        """
+        Predict loan eligibility
+        Returns: Approval probability (0-100), risk level, recommendations
+        """
+        try:
+            # Prepare features
+            features = np.array([[
+                salary, credit_score, existing_loans,
+                employment_years, age, loan_amount
+            ]])
+            
+            # Normalize
+            features_scaled = self.scaler.transform(features)
+            
+            # Predict probability
+            approval_prob = self.classifier.predict_proba(features_scaled)[0][1] * 100
+            
+            # Calculate risk level
+            if approval_prob >= 80:
+                risk_level = "LOW RISK ✅"
+            elif approval_prob >= 60:
+                risk_level = "MEDIUM RISK ⚠️"
+            elif approval_prob >= 40:
+                risk_level = "HIGH RISK ❌"
+            else:
+                risk_level = "VERY HIGH RISK ❌"
+            
+            return approval_prob, risk_level
+        
+        except Exception as e:
+            print(f"Error in prediction: {e}")
+            return 50, "UNKNOWN RISK"
+    
+    def check_eligibility_rules(self, salary, credit_score, existing_loans, 
+                               employment_years, age, loan_amount):
+        """
+        Check basic eligibility rules
+        Returns: Boolean and list of issues
+        """
+        issues = []
+        
+        # Age check
+        if age < 21:
+            issues.append("Age must be at least 21 years")
+        if age > 65:
+            issues.append("Age exceeds maximum limit (65 years)")
+        
+        # Employment check
+        if employment_years < 1:
+            issues.append("Minimum 1 year employment required")
+        
+        # Credit score check
+        if credit_score < 600:
+            issues.append("Credit score too low (minimum 600 required)")
+        
+        # Salary check
+        if salary < 25000:
+            issues.append("Salary too low for loan eligibility")
+        
+        # Loan amount vs salary ratio
+        emi_amount = calculate_emi(loan_amount, 12, 10)  # Assume 12% rate, 10 years
+        if (emi_amount / salary) > 0.5:  # EMI shouldn't exceed 50% of salary
+            issues.append(f"EMI of ₹{emi_amount:.2f} exceeds 50% of salary")
+        
+        # Existing loans check
+        if existing_loans > 3:
+            issues.append("Too many existing loans")
+        
+        is_eligible = len(issues) == 0
+        return is_eligible, issues
+    
+    def calculate_loan_score(self, salary, credit_score, existing_loans, 
+                            employment_years, age, loan_amount):
+        """
+        Calculate comprehensive loan score (0-100)
+        Considers multiple factors
+        """
+        score = 0
+        
+        # Credit score weight (40%)
+        credit_component = (min(credit_score, 850) / 850) * 40
+        score += credit_component
+        
+        # Salary weight (30%)
+        salary_component = min((salary / 500000) * 30, 30)
+        score += salary_component
+        
+        # Employment years weight (15%)
+        employment_component = min((employment_years / 30) * 15, 15)
+        score += employment_component
+        
+        # Existing loans weight (10%) - negative impact
+        loan_penalty = min(existing_loans * 2, 10)
+        score -= loan_penalty
+        
+        # Age factor (5%) - younger is better
+        age_component = min(((65 - age) / 45) * 5, 5)
+        score += age_component
+        
+        # Loan affordability (penalties if high)
+        emi = calculate_emi(loan_amount, 12, 10)
+        if (emi / salary) > 0.5:
+            score -= 15
+        elif (emi / salary) > 0.4:
+            score -= 10
+        
+        return max(0, min(score, 100))
+
+def calculate_emi(principal, rate_per_annum=10, years=10):
+    """
+    Calculate EMI (Equated Monthly Installment)
+    Formula: EMI = P * r * (1+r)^n / ((1+r)^n - 1)
+    """
+    monthly_rate = rate_per_annum / 100 / 12
+    months = years * 12
+    
+    if monthly_rate == 0:
+        return principal / months
+    
+    emi = principal * monthly_rate * ((1 + monthly_rate) ** months) / (
+        ((1 + monthly_rate) ** months) - 1
+    )
+    return emi
+
+def calculate_loan_eligibility(salary, credit_score, existing_loans, 
+                              employment_years, age, loan_amount):
+    """Main function to calculate loan eligibility"""
+    predictor = LoanEligibilityPredictor()
+    
+    # Check basic eligibility
+    is_eligible, issues = predictor.check_eligibility_rules(
+        salary, credit_score, existing_loans, employment_years, age, loan_amount
+    )
+    
+    # Get ML prediction
+    approval_prob, risk_level = predictor.predict_eligibility(
+        salary, credit_score, existing_loans, employment_years, age, loan_amount
+    )
+    
+    # Calculate loan score
+    loan_score = predictor.calculate_loan_score(
+        salary, credit_score, existing_loans, employment_years, age, loan_amount
+    )
+    
+    # Calculate EMI
+    emi = calculate_emi(loan_amount, 12, 10)
+    
+    # Get recommendations
+    recommendations = get_loan_recommendations(
+        approval_prob, salary, credit_score, existing_loans, employment_years, emi
+    )
+    
+    result = {
+        "approval_probability": round(approval_prob, 1),
+        "approval_status": "APPROVED ✅" if approval_prob >= 60 else "REJECTED ❌" if approval_prob < 40 else "UNDER REVIEW ⏳",
+        "risk_level": risk_level,
+        "loan_score": round(loan_score, 1),
+        "is_rule_eligible": is_eligible,
+        "issues": issues,
+        "emi": round(emi, 2),
+        "total_amount": round(loan_amount + (emi * 12 * 10) - loan_amount, 2),
+        "monthly_emi": round(emi, 2),
+        "tenure_years": 10,
+        "rate_per_annum": 12,
+        "recommendations": recommendations
+    }
+    
+    return result
+
+def get_loan_recommendations(approval_prob, salary, credit_score, 
+                            existing_loans, employment_years, emi):
+    """Generate personalized loan recommendations"""
+    recommendations = []
+    
+    if approval_prob >= 80:
+        recommendations.append("✅ You are likely to get approved for this loan amount")
+    elif approval_prob < 40:
+        recommendations.append("❌ Your approval chances are low. Consider these options:")
+        
+        if credit_score < 700:
+            recommendations.append("  • Improve your credit score to 700+")
+        
+        if existing_loans > 2:
+            recommendations.append("  • Pay off existing loans to improve your profile")
+        
+        recommendations.append("  • Apply for a smaller loan amount")
+        recommendations.append("  • Increase your employment tenure")
+    
+    else:
+        recommendations.append("⏳ Your application will be under review")
+    
+    # EMI affordability
+    emi_ratio = (emi / salary) * 100
+    if emi_ratio > 50:
+        recommendations.append(f"⚠️ Your EMI (₹{emi:.2f}) is {emi_ratio:.1f}% of salary. Consider reducing loan amount.")
+    elif emi_ratio < 30:
+        recommendations.append(f"✅ Your EMI to salary ratio ({emi_ratio:.1f}%) is very healthy")
+    
+    return recommendations
+
+def generate_loan_comparison(loan_amount, rates=[9, 10, 11, 12, 13], tenure_years=[5, 7, 10]):
+    """Generate EMI comparison for different rates and tenures"""
+    comparison_data = []
+    
+    for rate in rates:
+        for tenure in tenure_years:
+            emi = calculate_emi(loan_amount, rate, tenure)
+            total_amount = (emi * 12 * tenure)
+            interest = total_amount - loan_amount
+            
+            comparison_data.append({
+                "rate": f"{rate}%",
+                "tenure": f"{tenure} years",
+                "emi": round(emi, 2),
+                "total_amount": round(total_amount, 2),
+                "interest": round(interest, 2)
+            })
+    
+    return comparison_data

backend/app/ai/ollama_integration.py

@@ -0,0 +1,369 @@
+import os
+import requests
+import json
+import time
+
+# ─── Backend credentials (read once at module load) ───────────────────────────
+OPENAI_API_KEY = os.environ.get("OPENAI_API_KEY", "")
+OPENAI_MODEL   = os.environ.get("OPENAI_MODEL", "gpt-4o-mini")
+GROQ_API_KEY   = os.environ.get("GROQ_API_KEY", "")
+USE_GROQ       = bool(GROQ_API_KEY)
+
+OLLAMA_URL = "http://127.0.0.1:11434"
+
+# Check active backends once at load time to prevent timeout delays during requests.
+# Priority: OpenAI → Groq → local Ollama
+AI_BACKEND_AVAILABLE = False
+if OPENAI_API_KEY or GROQ_API_KEY:
+    AI_BACKEND_AVAILABLE = True
+else:
+    try:
+        # Fast 0.5s ping to local Ollama
+        response = requests.get(f"{OLLAMA_URL}/", timeout=0.5)
+        AI_BACKEND_AVAILABLE = (response.status_code == 200)
+    except Exception:
+        AI_BACKEND_AVAILABLE = False
+
+def has_active_ai_backend() -> bool:
+    """Returns True if OpenAI, Groq, or local Ollama is active and reachable."""
+    return AI_BACKEND_AVAILABLE
+
+BANKING_KEYWORDS = [
+    "account", "loan", "card", "balance",
+    "transfer", "bank", "interest", "emi",
+    "credit", "debit", "kyc", "upi", "cheque",
+    "deposit", "fd", "rd", "branch", "ifsc",
+    "transaction", "payment", "savings", "checking",
+    "mortgage", "investment", "fintech", "wallet",
+    "rate", "rates", "support", "customer", "care",
+    "help", "contact", "helpline", "number", "call",
+    "document", "required", "identity", "proof", "open"
+]
+
+SYSTEM_PROMPT = """You are BankBot, a professional banking assistant for Central Bank.
+You ONLY answer banking-related questions. If the question is not related to banking, politely refuse.
+Never answer questions about politics, sports, entertainment, coding, or personal advice.
+
+CORE GUIDELINES:
+1. ALWAYS communicate in {language}.
+2. CONTEXT AWARENESS: Use the provided chat history to understand follow-up questions. For example, if the user asks "What is the interest rate?" and then "for home loan", you must understand they are asking about home loan interest rates.
+3. CLARIFYING QUESTIONS: If a user's query is ambiguous (e.g., "how much?"), ask for missing details (e.g., "How much for what service? Balance check or loan EMI?").
+4. CALCULATIONS: Perform financial calculations (EMI, Interest, Eligibility) if information is provided.
+5. DOCUMENT ANALYSIS: If text from a PDF statement is provided, summarize it or answer specific questions about it.
+6. PROFESSIONALISM: Maintain a helpful, formal, and secure tone."""
+
+OLLAMA_URL = "http://127.0.0.1:11434"
+DEFAULT_OLLAMA_MODEL = os.environ.get("OLLAMA_MODEL", "llama3:latest")
+
+
+def is_banking_query(user_input):
+    input_lower = user_input.lower()
+    return any(word in input_lower for word in BANKING_KEYWORDS)
+
+
+def get_active_backend():
+    """Returns the highest-priority available backend name."""
+    if OPENAI_API_KEY:
+        return "openai"
+    if USE_GROQ:
+        return "groq"
+    return "ollama"
+
+
+def _build_messages(prompt, history=None, language="English"):
+    sys_prompt = SYSTEM_PROMPT.format(language=language)
+    messages = [{"role": "system", "content": sys_prompt}]
+
+    if history:
+        for msg in history[-10:]:
+            if msg.get("role") and msg.get("content"):
+                messages.append({"role": msg["role"], "content": msg["content"]})
+
+    messages.append({"role": "user", "content": prompt})
+    return messages
+
+
+def _get_available_ollama_models():
+    try:
+        response = requests.get(f"{OLLAMA_URL}/api/tags", timeout=5)
+        response.raise_for_status()
+        data = response.json()
+        return [model.get("name", "") for model in data.get("models", []) if model.get("name")]
+    except Exception as e:
+        print(f"Ollama model discovery error: {e}")
+        return []
+
+
+def _resolve_ollama_model(requested_model):
+    available_models = _get_available_ollama_models()
+    if not available_models:
+        return requested_model
+
+    if requested_model in available_models:
+        return requested_model
+
+    base_requested_model = requested_model.split(":", 1)[0]
+    for candidate in available_models:
+        if candidate.split(":", 1)[0] == base_requested_model:
+            return candidate
+
+    return available_models[0]
+
+
+def _ollama_error_message(model, error):
+    return (
+        f"Ollama request failed for model '{model}': {error}. "
+        "The Ollama server is reachable, but the model backend crashed internally. "
+        "Try `ollama run llama3`, and if that fails restart Ollama with "
+        "`taskkill /F /IM ollama.exe` followed by `ollama serve`."
+    )
+
+
+# ─── OpenAI Functions ────────────────────────────────────────────────────────
+
+def get_openai_response(prompt, history=None, model=None, language="English"):
+    """Fetches a response from the OpenAI API (gpt-4o-mini by default)."""
+    if not OPENAI_API_KEY:
+        return None
+    try:
+        from openai import OpenAI
+        client = OpenAI(api_key=OPENAI_API_KEY)
+        target_model = model or OPENAI_MODEL
+
+        sys_prompt = SYSTEM_PROMPT.format(language=language)
+        messages = [{"role": "system", "content": sys_prompt}]
+
+        if history:
+            for msg in history[-10:]:
+                if msg.get("role") and msg.get("content"):
+                    messages.append({"role": msg["role"], "content": msg["content"]})
+
+        messages.append({"role": "user", "content": prompt})
+
+        response = client.chat.completions.create(
+            model=target_model,
+            messages=messages,
+            temperature=0.1,
+            max_tokens=1000,
+        )
+        return response.choices[0].message.content
+    except Exception as e:
+        print(f"OpenAI Error: {e}")
+        return None
+
+
+def stream_openai_response(prompt, history=None, model=None, language="English"):
+    """Yields streamed response chunks from the OpenAI API."""
+    if not OPENAI_API_KEY:
+        return
+    try:
+        from openai import OpenAI
+        client = OpenAI(api_key=OPENAI_API_KEY)
+        target_model = model or OPENAI_MODEL
+
+        sys_prompt = SYSTEM_PROMPT.format(language=language)
+        messages = [{"role": "system", "content": sys_prompt}]
+
+        if history:
+            for msg in history[-10:]:
+                if msg.get("role") and msg.get("content"):
+                    messages.append({"role": msg["role"], "content": msg["content"]})
+
+        messages.append({"role": "user", "content": prompt})
+
+        stream = client.chat.completions.create(
+            model=target_model,
+            messages=messages,
+            temperature=0.1,
+            max_tokens=1000,
+            stream=True,
+        )
+        for chunk in stream:
+            content = chunk.choices[0].delta.content
+            if content:
+                yield content
+    except Exception as e:
+        print(f"OpenAI Stream Error: {e}")
+
+
+# ─── Groq AI Functions ────────────────────────────────────────────────────────
+
+def get_groq_response(prompt, history=None, model="llama-3.3-70b-versatile", language="English"):
+    """Fetches a response from Groq AI API."""
+    try:
+        from groq import Groq
+        client = Groq(api_key=GROQ_API_KEY)
+
+        sys_prompt = SYSTEM_PROMPT.format(language=language)
+        messages = [{"role": "system", "content": sys_prompt}]
+
+        if history:
+            for msg in history[-10:]:
+                if msg.get("role") and msg.get("content"):
+                    messages.append({"role": msg["role"], "content": msg["content"]})
+
+        messages.append({"role": "user", "content": prompt})
+
+        response = client.chat.completions.create(
+            model=model,
+            messages=messages,
+            temperature=0.1,
+            max_tokens=1000,
+        )
+        return response.choices[0].message.content
+    except Exception as e:
+        print(f"Groq Error: {e}")
+        return None
+
+
+def stream_groq_response(prompt, history=None, model="llama-3.3-70b-versatile", language="English"):
+    """Yields streamed response chunks from Groq AI API."""
+    try:
+        from groq import Groq
+        client = Groq(api_key=GROQ_API_KEY)
+
+        sys_prompt = SYSTEM_PROMPT.format(language=language)
+        messages = [{"role": "system", "content": sys_prompt}]
+
+        if history:
+            for msg in history[-10:]:
+                if msg.get("role") and msg.get("content"):
+                    messages.append({"role": msg["role"], "content": msg["content"]})
+
+        messages.append({"role": "user", "content": prompt})
+
+        stream = client.chat.completions.create(
+            model=model,
+            messages=messages,
+            temperature=0.1,
+            max_tokens=1000,
+            stream=True,
+        )
+        for chunk in stream:
+            content = chunk.choices[0].delta.content
+            if content:
+                yield content
+    except Exception as e:
+        print(f"Groq Stream Error: {e}")
+        yield None
+
+
+# ─── Ollama Functions ─────────────────────────────────────────────────────────
+
+def get_ollama_response(prompt, history=None, model=DEFAULT_OLLAMA_MODEL, language="English"):
+    """Fetches a response from a local Ollama instance."""
+    url = f"{OLLAMA_URL}/api/chat"
+    resolved_model = _resolve_ollama_model(model)
+    messages = _build_messages(prompt, history=history, language=language)
+
+    payload = {
+        "model": resolved_model,
+        "messages": messages,
+        "stream": False,
+        "options": {"temperature": 0.1, "top_p": 0.9, "num_predict": 500}
+    }
+
+    try:
+        # (connect_timeout, read_timeout) — cap total generation at 25s
+        response = requests.post(url, json=payload, timeout=(5, 25))
+        response.raise_for_status()
+        data = response.json()
+        return data.get("message", {}).get("content", "")
+    except requests.exceptions.Timeout:
+        # Don't retry on timeout — let the caller fall back to the next backend
+        print(f"Ollama timed out for model '{resolved_model}'. Falling back to next backend.")
+        return None
+    except Exception as e:
+        print(_ollama_error_message(resolved_model, e))
+        if resolved_model != "llama3":
+            return get_ollama_response(prompt, history, model="llama3", language=language)
+        return None
+
+
+def stream_ollama_response(prompt, history=None, model=DEFAULT_OLLAMA_MODEL, language="English"):
+    """Yields chunks of the response from a local Ollama instance for streaming."""
+    url = f"{OLLAMA_URL}/api/chat"
+    resolved_model = _resolve_ollama_model(model)
+    messages = _build_messages(prompt, history=history, language=language)
+
+    payload = {
+        "model": resolved_model,
+        "messages": messages,
+        "stream": True,
+        "options": {"temperature": 0.1, "top_p": 0.9, "num_predict": 500}
+    }
+
+    try:
+        # (connect_timeout, read_timeout) — cap total generation at 25s
+        response = requests.post(url, json=payload, timeout=(5, 25), stream=True)
+        response.raise_for_status()
+
+        for line in response.iter_lines():
+            if line:
+                chunk = json.loads(line)
+                if 'message' in chunk and 'content' in chunk['message']:
+                    yield chunk['message']['content']
+                if chunk.get('done'):
+                    break
+    except requests.exceptions.Timeout:
+        # Don't retry on timeout — let the caller fall back to the next backend
+        print(f"Ollama stream timed out for model '{resolved_model}'. Falling back to next backend.")
+        return
+    except Exception as e:
+        print(_ollama_error_message(resolved_model, e))
+        if resolved_model != "llama3":
+            yield from stream_ollama_response(prompt, history, model="llama3", language=language)
+        else:
+            yield None
+
+
+# ─── Unified Wrapper Functions ────────────────────────────────────────────────
+
+def get_ai_response(prompt, history=None, language="English"):
+    """
+    Auto-selects the best available backend.
+    Priority: OpenAI → Groq → Ollama
+    Returns None only when all backends are unavailable.
+    """
+    if OPENAI_API_KEY:
+        result = get_openai_response(prompt, history, language=language)
+        if result:
+            return result
+
+    if USE_GROQ:
+        result = get_groq_response(prompt, history, language=language)
+        if result:
+            return result
+
+    return get_ollama_response(prompt, history, language=language)
+
+
+def stream_ai_response(prompt, history=None, language="English"):
+    """
+    Auto-selects streaming from the best available backend.
+    Priority: OpenAI → Groq → Ollama
+    """
+    if OPENAI_API_KEY:
+        chunks = list(stream_openai_response(prompt, history, language=language))
+        if chunks:
+            yield from chunks
+            return
+
+    if USE_GROQ:
+        chunks = list(stream_groq_response(prompt, history, language=language))
+        if chunks:
+            yield from chunks
+            return
+
+    yield from stream_ollama_response(prompt, history, language=language)
+
+
+def check_ollama_connection():
+    """Checks if the local Ollama server is running."""
+    if USE_GROQ:
+        return True
+    try:
+        response = requests.get(f"{OLLAMA_URL}/", timeout=2)
+        return response.status_code == 200
+    except:
+        return False

backend/app/ai/router.py

@@ -0,0 +1,181 @@
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy.orm import Session
+from pydantic import BaseModel
+from typing import List, Optional
+
+from app.database.database import get_db
+from app.database.models import User
+from app.middleware.cache import cache
+
+# Import AI helper engines
+from app.ai.forecasting import predict_future_balance, forecast_savings_and_investments, simulate_future_scenarios
+from app.ai.simulation import simulate_purchase_impact, simulate_investment_impact, simulate_subscription_cancellation
+from app.ai.behavior import analyze_spending_behavior
+from app.ai.coaching import calculate_financial_health_score, generate_daily_briefing
+from app.ai.subscriptions import analyze_subscriptions
+from app.ai.fraud import evaluate_transaction_for_fraud, get_user_fraud_alerts
+from app.ai.chat import get_chat_response
+
+router = APIRouter(prefix="/api/ai", tags=["AI Intelligence"])
+
+# Fallback helper to retrieve a valid user ID for demonstration
+def get_user_id_fallback(db: Session, user_id: Optional[str] = None) -> str:
+    if user_id:
+        return user_id
+    user = db.query(User).first()
+    if not user:
+        raise HTTPException(status_code=404, detail="No users found in database. Please seed the database first.")
+    return user.id
+
+# Pydantic Schemas for input
+class PurchaseRequest(BaseModel):
+    amount: float
+    merchant: str
+    category: str
+
+class InvestmentRequest(BaseModel):
+    monthly_sip: float
+    asset_type: str
+    lump_sum: float = 0.0
+
+class SubscriptionSimulationRequest(BaseModel):
+    subscription_ids: List[str]
+
+class ChatMessageRequest(BaseModel):
+    message: str
+
+# ─── FINANCIAL TWIN FORECASTS ──────────────────────────────────────────────────
+
+@router.get("/twin/predict")
+def get_twin_predict(user_id: Optional[str] = None, db: Session = Depends(get_db)):
+    uid = get_user_id_fallback(db, user_id)
+    cache_key = f"ai:twin:predict:{uid}"
+    
+    cached = cache.get(cache_key)
+    if cached:
+        return cached
+        
+    result = predict_future_balance(db, uid)
+    cache.set(cache_key, result, ttl=300) # cache for 5 minutes
+    return result
+
+@router.get("/twin/future")
+def get_twin_future(user_id: Optional[str] = None, months: int = Query(default=12, ge=1, le=60), db: Session = Depends(get_db)):
+    uid = get_user_id_fallback(db, user_id)
+    cache_key = f"ai:twin:future:{uid}:{months}"
+    
+    cached = cache.get(cache_key)
+    if cached:
+        return cached
+        
+    result = forecast_savings_and_investments(db, uid, months)
+    cache.set(cache_key, result, ttl=300)
+    return result
+
+@router.get("/twin/scenarios")
+def get_twin_scenarios(user_id: Optional[str] = None, months: int = Query(default=6, ge=1, le=24), db: Session = Depends(get_db)):
+    uid = get_user_id_fallback(db, user_id)
+    cache_key = f"ai:twin:scenarios:{uid}:{months}"
+    
+    cached = cache.get(cache_key)
+    if cached:
+        return cached
+        
+    result = simulate_future_scenarios(db, uid, months)
+    cache.set(cache_key, result, ttl=300)
+    return result
+
+# ─── SIMULATION ENDPOINTS ──────────────────────────────────────────────────────
+
+@router.post("/simulate/purchase")
+def post_simulate_purchase(req: PurchaseRequest, user_id: Optional[str] = None, db: Session = Depends(get_db)):
+    uid = get_user_id_fallback(db, user_id)
+    return simulate_purchase_impact(db, uid, req.amount, req.category, req.merchant)
+
+@router.post("/simulate/investment")
+def post_simulate_investment(req: InvestmentRequest, user_id: Optional[str] = None, db: Session = Depends(get_db)):
+    uid = get_user_id_fallback(db, user_id)
+    return simulate_investment_impact(db, uid, req.monthly_sip, req.asset_type, req.lump_sum)
+
+@router.post("/simulate/subscription")
+def post_simulate_subscription(req: SubscriptionSimulationRequest, user_id: Optional[str] = None, db: Session = Depends(get_db)):
+    uid = get_user_id_fallback(db, user_id)
+    return simulate_subscription_cancellation(db, uid, req.subscription_ids)
+
+# ─── BEHAVIORAL ANALYTICS ─────────────────────────────────────────────────────
+
+@router.get("/behavior/insights")
+def get_behavior_insights(user_id: Optional[str] = None, db: Session = Depends(get_db)):
+    uid = get_user_id_fallback(db, user_id)
+    cache_key = f"ai:behavior:insights:{uid}"
+    
+    cached = cache.get(cache_key)
+    if cached:
+        return cached
+        
+    result = analyze_spending_behavior(db, uid)
+    cache.set(cache_key, result, ttl=600) # cache for 10 minutes
+    return result
+
+# ─── COACHING & BRIEFINGS ─────────────────────────────────��───────────────────
+
+@router.get("/coaching/briefing")
+def get_coaching_briefing(user_id: Optional[str] = None, db: Session = Depends(get_db)):
+    uid = get_user_id_fallback(db, user_id)
+    # Cache briefings for 1 hour to prevent excessive LLM costs
+    cache_key = f"ai:coaching:briefing:{uid}"
+    
+    cached = cache.get(cache_key)
+    if cached:
+        return cached
+        
+    result = generate_daily_briefing(db, uid)
+    cache.set(cache_key, result, ttl=3600)
+    return result
+
+@router.get("/coaching/score")
+def get_coaching_score(user_id: Optional[str] = None, db: Session = Depends(get_db)):
+    uid = get_user_id_fallback(db, user_id)
+    cache_key = f"ai:coaching:score:{uid}"
+    
+    cached = cache.get(cache_key)
+    if cached:
+        return cached
+        
+    result = calculate_financial_health_score(db, uid)
+    cache.set(cache_key, result, ttl=600)
+    return result
+
+# ─── SUBSCRIPTION OPTIMIZATION ────────────────────────────────────────────────
+
+@router.get("/subscriptions/optimize")
+def get_subscriptions_optimize(user_id: Optional[str] = None, db: Session = Depends(get_db)):
+    uid = get_user_id_fallback(db, user_id)
+    cache_key = f"ai:subs:optimize:{uid}"
+    
+    cached = cache.get(cache_key)
+    if cached:
+        return cached
+        
+    result = analyze_subscriptions(db, uid)
+    cache.set(cache_key, result, ttl=600)
+    return result
+
+# ─── FRAUD & SECURITY ─────────────────────────────────────────────────────────
+
+@router.get("/fraud/analysis")
+def get_fraud_analysis(user_id: Optional[str] = None, db: Session = Depends(get_db)):
+    uid = get_user_id_fallback(db, user_id)
+    return get_user_fraud_alerts(db, uid)
+
+@router.post("/fraud/evaluate/{transaction_id}")
+def post_fraud_evaluate(transaction_id: str, db: Session = Depends(get_db)):
+    return evaluate_transaction_for_fraud(db, transaction_id)
+
+# ─── CONTEXTUAL CHAT ENDPOINT ──────────────────────────────────────────────────
+
+@router.post("/chat")
+def post_chat(req: ChatMessageRequest, user_id: Optional[str] = None, db: Session = Depends(get_db)):
+    uid = get_user_id_fallback(db, user_id)
+    response_msg = get_chat_response(db, uid, req.message)
+    return {"response": response_msg}

backend/app/ai/simulation.py

@@ -0,0 +1,204 @@
+from sqlalchemy.orm import Session
+from app.database.models import Account, Goal, Investment, Subscription
+from app.ai.forecasting import get_cashflow_metrics
+
+def simulate_purchase_impact(db: Session, user_id: str, amount: float, category: str, merchant: str):
+    """
+    Simulates buying a large asset or item (e.g. a car) and assesses risk.
+    """
+    accounts = db.query(Account).filter(Account.user_id == user_id).all()
+    total_balance = sum(acc.balance for acc in accounts)
+    checking_acc = next((a for a in accounts if a.type.lower() == "checking"), None)
+    
+    # Target emergency fund amount
+    goals = db.query(Goal).filter(Goal.user_id == user_id).all()
+    emergency_goal = next((g for g in goals if "emergency" in g.title.lower()), None)
+    emergency_threshold = emergency_goal.target_amount if emergency_goal else 3000.0
+    
+    new_balance = total_balance - amount
+    
+    # Cashflow metrics
+    _, daily_income, daily_spending = get_cashflow_metrics(db, user_id)
+    monthly_net = (daily_income - daily_spending) * 30.4
+    
+    # Risk Analysis
+    risk_level = "low"
+    reasons = []
+    
+    if amount > total_balance:
+        risk_level = "critical"
+        reasons.append("Purchase exceeds your total available balance, requiring debt.")
+    elif new_balance < emergency_threshold:
+        risk_level = "high"
+        reasons.append(f"This purchase depletes your emergency buffer (threshold of ${emergency_threshold:,.2f}).")
+    elif amount > total_balance * 0.3:
+        risk_level = "medium"
+        reasons.append("Single purchase consumes more than 30% of your total liquid cash.")
+        
+    if monthly_net < 0 and amount > 500:
+        risk_level = "high"
+        reasons.append("You have a negative monthly cashflow; making large purchases increases financial strain.")
+        
+    # Recommendations
+    recommendation = ""
+    if risk_level == "critical":
+        recommendation = "❌ Strongly advise against this purchase. Consider financing options, delaying, or establishing a dedicated goal."
+    elif risk_level == "high":
+        recommendation = "⚠️ Refrain from this purchase if possible. Rebuilding your emergency fund should be prioritized."
+    elif risk_level == "medium":
+        recommendation = "💡 Proceed with caution. Consider trimming discretionary expenses next month to offset the cost."
+    else:
+        recommendation = "✅ Purchase is safe. It fits within your financial profile without impacting key safety buffers."
+        
+    return {
+        "purchase_amount": amount,
+        "merchant": merchant,
+        "category": category,
+        "current_balance": round(total_balance, 2),
+        "projected_balance": round(max(0.0, new_balance), 2),
+        "savings_impact": {
+            "immediate_reduction": round(amount, 2),
+            "emergency_buffer_breached": new_balance < emergency_threshold,
+            "emergency_threshold": round(emergency_threshold, 2)
+        },
+        "risk_analysis": {
+            "risk_level": risk_level,
+            "reasons": reasons
+        },
+        "recommendation": recommendation
+    }
+
+def simulate_investment_impact(db: Session, user_id: str, monthly_sip: float, asset_type: str, lump_sum: float = 0.0):
+    """
+    Simulates investment growth and evaluates opportunity cost.
+    """
+    # Expected annual returns based on asset type
+    returns_map = {
+        "stock": 0.10,        # 10%
+        "crypto": 0.20,       # 20%
+        "mutual_fund": 0.08,  # 8%
+        "fd": 0.05,           # 5%
+        "bond": 0.04          # 4%
+    }
+    apr = returns_map.get(asset_type.lower(), 0.07)
+    
+    # Calculate current balance
+    accounts = db.query(Account).filter(Account.user_id == user_id).all()
+    total_balance = sum(acc.balance for acc in accounts)
+    
+    # Cashflow metrics
+    _, daily_income, daily_spending = get_cashflow_metrics(db, user_id)
+    monthly_net = (daily_income - daily_spending) * 30.4
+    
+    # Check if SIP is affordable
+    is_affordable = monthly_net >= monthly_sip
+    
+    growth_projection = []
+    current_value = lump_sum
+    total_invested = lump_sum
+    
+    # 5-year monthly projection
+    for month in range(0, 61):
+        if month > 0:
+            current_value = (current_value + monthly_sip) * (1 + apr / 12)
+            total_invested += monthly_sip
+            
+        if month in [12, 36, 60]:  # Save 1, 3, 5 year markers
+            growth_projection.append({
+                "year": month // 12,
+                "total_invested": round(total_invested, 2),
+                "future_value": round(current_value, 2),
+                "earnings": round(max(0.0, current_value - total_invested), 2)
+            })
+            
+    risk_level = "low"
+    if asset_type.lower() == "crypto":
+        risk_level = "high"
+    elif asset_type.lower() in ["stock", "mutual_fund"] and monthly_sip > monthly_net * 0.5:
+        risk_level = "medium"
+        
+    recommendation = ""
+    if not is_affordable:
+        recommendation = f"⚠️ Your monthly net surplus (${monthly_net:,.2f}) is lower than the planned SIP (${monthly_sip:,.2f}). This may lead to checking overdrafts."
+    else:
+        recommendation = f"✅ Excellent choice. Investing ${monthly_sip:,.2f} monthly in {asset_type} is fully supported by your net cashflow."
+        
+    return {
+        "asset_type": asset_type,
+        "monthly_sip": round(monthly_sip, 2),
+        "lump_sum": round(lump_sum, 2),
+        "is_affordable": is_affordable,
+        "growth_projection": growth_projection,
+        "risk_analysis": {
+            "risk_level": risk_level,
+            "expected_annual_return": apr
+        },
+        "savings_impact": {
+            "opportunity_cost_yearly": round(monthly_sip * 12, 2),
+            "monthly_surplus_retaining": round(max(0.0, monthly_net - monthly_sip), 2)
+        },
+        "recommendation": recommendation
+    }
+
+def simulate_subscription_cancellation(db: Session, user_id: str, subscription_ids: list):
+    """
+    Simulates the financial benefit of cancelling one or more subscriptions.
+    """
+    subs = db.query(Subscription).filter(
+        Subscription.user_id == user_id,
+        Subscription.id.in_(subscription_ids)
+    ).all()
+    
+    if not subs:
+        return {"message": "No matching subscriptions found for cancellation simulation."}
+        
+    monthly_savings = 0.0
+    yearly_savings = 0.0
+    cancelled_details = []
+    
+    for sub in subs:
+        cost = sub.amount
+        is_monthly = sub.billing_cycle.lower() == "monthly"
+        
+        m_cost = cost if is_monthly else (cost / 12)
+        y_cost = (cost * 12) if is_monthly else cost
+        
+        monthly_savings += m_cost
+        yearly_savings += y_cost
+        
+        cancelled_details.append({
+            "id": sub.id,
+            "merchant": sub.merchant,
+            "amount": sub.amount,
+            "billing_cycle": sub.billing_cycle
+        })
+        
+    # Relate savings to user's Goals
+    goals = db.query(Goal).filter(Goal.user_id == user_id).all()
+    first_goal = goals[0] if goals else None
+    
+    goal_impact = None
+    if first_goal:
+        months_saved = 0.0
+        remaining_needed = max(0.0, first_goal.target_amount - first_goal.current_amount)
+        if monthly_savings > 0:
+            months_saved = remaining_needed / (remaining_needed / 12 if remaining_needed > 0 else 1) # simple logic
+            # Let's say if they direct this money to goal, it reduces target time by:
+            months_saved = (remaining_needed / monthly_savings) if remaining_needed > 0 else 0
+            
+        goal_impact = {
+            "goal_title": first_goal.title,
+            "target_amount": round(first_goal.target_amount, 2),
+            "months_to_reach_with_savings": round(months_saved, 1) if monthly_savings > 0 else 0
+        }
+        
+    # Recommendations
+    recommendation = f"Cancelling these subscriptions yields ${monthly_savings:,.2f} per month (${yearly_savings:,.2f} annually). Reinvesting these funds into high-yield savings or mutual funds is recommended."
+    
+    return {
+        "cancelled_subscriptions": cancelled_details,
+        "monthly_savings": round(monthly_savings, 2),
+        "yearly_savings": round(yearly_savings, 2),
+        "goal_impact": goal_impact,
+        "recommendation": recommendation
+    }

backend/app/ai/subscriptions.py

@@ -0,0 +1,105 @@
+from collections import defaultdict
+from sqlalchemy.orm import Session
+from app.database.models import Subscription
+
+def analyze_subscriptions(db: Session, user_id: str):
+    """
+    Analyzes subscriptions to detect duplicates, unused memberships, and cancellation opportunities.
+    """
+    subs = db.query(Subscription).filter(
+        Subscription.user_id == user_id,
+        Subscription.active == True
+    ).all()
+    
+    if not subs:
+        return {
+            "subscriptions": [],
+            "duplicates": [],
+            "unused_subscriptions": [],
+            "yearly_savings_potential": 0.0,
+            "risk_analysis": []
+        }
+        
+    merchant_map = defaultdict(list)
+    unused_list = []
+    cancellation_suggestions = []
+    yearly_savings = 0.0
+    risk_analysis = []
+    
+    for s in subs:
+        # Standardize merchant name to detect duplicates
+        clean_merchant = s.merchant.strip().lower()
+        merchant_map[clean_merchant].append(s)
+        
+        # Determine cost
+        m_cost = s.amount if s.billing_cycle.lower() == "monthly" else (s.amount / 12)
+        y_cost = (s.amount * 12) if s.billing_cycle.lower() == "monthly" else s.amount
+        
+        # Detect unused (if frequency is 'low' or 'none' in usage detection metadata)
+        usage = s.ai_usage_detection or {}
+        freq = str(usage.get("usage_frequency", "medium")).lower()
+        
+        if freq in ["low", "none", "unused"]:
+            unused_list.append(s)
+            cancellation_suggestions.append({
+                "subscription_id": s.id,
+                "merchant": s.merchant,
+                "amount": s.amount,
+                "billing_cycle": s.billing_cycle,
+                "reason": f"Usage frequency is flagged as '{freq}'.",
+                "yearly_savings": round(y_cost, 2)
+            })
+            yearly_savings += y_cost
+            
+    # Detect duplicates
+    duplicates = []
+    for merchant, items in merchant_map.items():
+        if len(items) > 1:
+            total_cost = sum(x.amount for x in items)
+            duplicates.append({
+                "merchant": items[0].merchant,
+                "count": len(items),
+                "items": [
+                    {
+                        "id": x.id,
+                        "amount": x.amount,
+                        "billing_cycle": x.billing_cycle
+                    }
+                    for x in items
+                ],
+                "recommendation": f"You have {len(items)} active subscriptions for {items[0].merchant}. Consolidate to a single account to save."
+            })
+            
+    # Risk Analysis (utilities vs entertainment)
+    essential_categories = ["electricity", "water", "gas", "internet", "phone", "insurance"]
+    for s in subs:
+        is_essential = any(k in s.merchant.lower() for k in essential_categories)
+        if is_essential:
+            risk_analysis.append({
+                "merchant": s.merchant,
+                "risk_level": "high",
+                "consequences": "Utility interruption, account reactivation fees, or legal service contract breaches."
+            })
+        else:
+            risk_analysis.append({
+                "merchant": s.merchant,
+                "risk_level": "low",
+                "consequences": "Loss of entertainment streaming access only. Service can be reactivated instantly."
+            })
+            
+    return {
+        "subscriptions": [
+            {
+                "id": s.id,
+                "merchant": s.merchant,
+                "amount": s.amount,
+                "billing_cycle": s.billing_cycle,
+                "usage_frequency": s.ai_usage_detection.get("usage_frequency", "medium") if s.ai_usage_detection else "medium"
+            }
+            for s in subs
+        ],
+        "duplicates": duplicates,
+        "unused_subscriptions": cancellation_suggestions,
+        "yearly_savings_potential": round(yearly_savings, 2),
+        "risk_analysis": risk_analysis
+    }

backend/app/ai/voice_assistant.py

@@ -0,0 +1,219 @@
+"""
+Voice Banking Assistant for BankBot
+Enables voice-based banking queries and responses
+"""
+
+import os
+import json
+import speech_recognition as sr
+import pyttsx3
+from gtts import gTTS
+import io
+import streamlit as st
+from datetime import datetime
+
+class VoiceAssistant:
+    """Handles voice input and output for banking queries"""
+    
+    def __init__(self):
+        self.recognizer = sr.Recognizer()
+        self.engine = pyttsx3.init()
+        self.engine.setProperty('rate', 150)  # Speaking rate
+        self.microphone = sr.Microphone()
+        
+        # Initialize text-to-speech properties
+        self.engine.setProperty('volume', 0.9)  # Volume level (0.0 to 1.0)
+    
+    def listen_to_user(self, timeout=10):
+        """
+        Capture audio input from microphone and convert to text
+        Returns: Recognized text or None if recognition fails
+        """
+        try:
+            with self.microphone as source:
+                # Adjust for ambient noise
+                self.recognizer.adjust_for_ambient_noise(source, duration=0.5)
+                
+                # Listen for audio
+                audio = self.recognizer.listen(source, timeout=timeout, phrase_time_limit=15)
+                
+                # Try to recognize using Google Speech Recognition
+                text = self.recognizer.recognize_google(audio)
+                return text.lower()
+        
+        except sr.RequestError as e:
+            return None  # Could not request results; network error
+        except sr.UnknownValueError:
+            return None  # Unable to recognize speech
+        except Exception as e:
+            print(f"Error listening to user: {e}")
+            return None
+    
+    def speak_response(self, text, use_gtts=False):
+        """
+        Provide audio output for the response
+        Args:
+            text: Response text
+            use_gtts: Use Google Text-to-Speech instead of pyttsx3
+        Returns: Audio data or None
+        """
+        try:
+            if use_gtts:
+                # Use Google TTS (requires internet, better quality)
+                tts = gTTS(text=text, lang='en', slow=False)
+                audio_fp = io.BytesIO()
+                tts.write_to_fp(audio_fp)
+                audio_fp.seek(0)
+                return audio_fp
+            else:
+                # Use pyttsx3 (offline, works locally)
+                self.engine.say(text)
+                self.engine.runAndWait()
+                return True
+        
+        except Exception as e:
+            print(f"Error in text-to-speech: {e}")
+            return None
+    
+    def process_voice_query(self, transcribed_text, user_data, transactions):
+        """
+        Process voice query and extract banking intent
+        Returns: Query type, extracted information
+        """
+        text_lower = transcribed_text.lower()
+        
+        # Balance query
+        if any(word in text_lower for word in ["balance", "how much", "account balance"]):
+            return "balance", None
+        
+        # Transaction history
+        elif any(word in text_lower for word in ["transactions", "history", "recent", "last"]):
+            return "transactions", None
+        
+        # Spending analysis
+        elif any(word in text_lower for word in ["spending", "spent", "expenses", "how much did i spend"]):
+            return "spending", None
+        
+        # Transfer query
+        elif any(word in text_lower for word in ["transfer", "send", "pay"]):
+            return "transfer", None
+        
+        # Loan info
+        elif any(word in text_lower for word in ["loan", "emi", "borrow", "credit"]):
+            return "loan", None
+        
+        # FD/Investment
+        elif any(word in text_lower for word in ["fixed deposit", "fd", "invest", "investment"]):
+            return "fd", None
+        
+        # Help/Support
+        elif any(word in text_lower for word in ["help", "support", "assist", "how do i"]):
+            return "help", None
+        
+        else:
+            return "general", None
+    
+    def generate_voice_response(self, query_type, user_data, transactions, get_ai_response_fn=None):
+        """
+        Generate appropriate response for voice query
+        Returns: Response text and audio
+        """
+        balance = user_data.get('balance', 0)
+        
+        if query_type == "balance":
+            response = f"Your current account balance is rupees {balance:.2f}"
+        
+        elif query_type == "transactions":
+            recent = transactions[:5] if transactions else []
+            if not recent:
+                response = "You have no recent transactions."
+            else:
+                response = f"Your last transaction was {recent[0].get('amount')} rupees for {recent[0].get('details', 'banking service')}"
+        
+        elif query_type == "spending":
+            # Calculate spending
+            debit_txns = [t for t in transactions if t.get('type') == 'debit']
+            total_spent = sum(float(t.get('amount', 0)) for t in debit_txns[-10:])
+            response = f"You have spent {total_spent:.2f} rupees in your recent transactions."
+        
+        elif query_type == "help":
+            response = "I can help you with balance inquiries, transaction history, spending analysis, fund transfers, and loan information. What would you like to know?"
+        
+        elif query_type == "general" and get_ai_response_fn:
+            # Use AI for general banking queries
+            response = get_ai_response_fn("user query", [])
+        
+        else:
+            response = "I didn't quite understand. Could you please rephrase your question?"
+        
+        return response
+    
+    def extract_voice_command(self, transcribed_text):
+        """Extract command-specific parameters from voice input"""
+        # Extract amounts from voice
+        amount_words = {
+            "hundred": 100, "thousand": 1000, "lakh": 100000,
+            "rupees": 1, "rupee": 1, "paisa": 0.01
+        }
+        
+        # Extract recipient name if present
+        # Extract date references if present
+        
+        return None
+
+def record_voice_query(username, users_data, get_ai_response_fn):
+    """
+    Record and process voice query through Streamlit UI
+    """
+    st.markdown("""
+    <div style="background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); 
+                padding: 20px; border-radius: 10px; margin: 10px 0;">
+        <h3 style="color: white; margin: 0;">🎤 Voice Banking Assistant</h3>
+    </div>
+    """, unsafe_allow_html=True)
+    
+    col1, col2, col3 = st.columns([1, 2, 1])
+    
+    with col2:
+        if st.button("🎙️ Start Recording", key="voice_record", use_container_width=True):
+            with st.spinner("🎧 Listening... Speak now!"):
+                assistant = VoiceAssistant()
+                recognized_text = assistant.listen_to_user(timeout=10)
+                
+                if recognized_text:
+                    st.success(f"✅ Recognized: {recognized_text}")
+                    
+                    # Process the query
+                    user_data = users_data.get(username, {})
+                    transactions = user_data.get('transactions', [])
+                    
+                    query_type, _ = assistant.process_voice_query(recognized_text, user_data, transactions)
+                    response = assistant.generate_voice_response(
+                        query_type, 
+                        user_data, 
+                        transactions,
+                        get_ai_response_fn
+                    )
+                    
+                    # Display response
+                    st.info(f"🤖 Response: {response}")
+                    
+                    # Provide audio feedback
+                    with st.spinner("🔊 Converting to speech..."):
+                        assistant.speak_response(response, use_gtts=False)
+                    
+                    st.success("✅ Response delivered")
+                else:
+                    st.error("❌ Could not recognize speech. Please try again.")
+
+def voice_mode_demo():
+    """Demo voice banking queries"""
+    demo_queries = [
+        "What's my balance?",
+        "Show my recent transactions",
+        "How much did I spend this month?",
+        "Transfer 5000 to John",
+        "Tell me about loan eligibility"
+    ]
+    
+    return demo_queries

backend/app/auth/router.py

@@ -0,0 +1,189 @@
+"""
+Authentication router — JWT login, register, refresh, logout.
+Uses bcrypt directly (avoids passlib 1.7.4 + bcrypt>=4 incompatibility).
+Uses python-jose for JWT.
+"""
+from datetime import datetime, timedelta
+from typing import Optional
+
+import bcrypt as _bcrypt
+from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
+from jose import JWTError, jwt
+from pydantic import BaseModel, EmailStr
+from sqlalchemy.orm import Session
+
+from app.database.database import get_db
+from app.database.models import User, generate_uuid
+import os
+
+router = APIRouter(prefix="/api/auth", tags=["Authentication"])
+
+# ─── Config ───────────────────────────────────────────────────────────────────
+SECRET_KEY = os.environ.get("JWT_SECRET_KEY", "bankbot-dev-secret-change-in-production")
+ALGORITHM = os.environ.get("JWT_ALGORITHM", "HS256")
+ACCESS_TOKEN_EXPIRE_MINUTES = int(os.environ.get("ACCESS_TOKEN_EXPIRE_MINUTES", "60"))
+REFRESH_TOKEN_EXPIRE_DAYS = 7
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/auth/login", auto_error=False)
+
+# ─── Schemas ──────────────────────────────────────────────────────────────────
+class RegisterRequest(BaseModel):
+    email: EmailStr
+    password: str
+    name: str
+
+class LoginResponse(BaseModel):
+    access_token: str
+    refresh_token: str
+    token_type: str = "bearer"
+    user_id: str
+    name: str
+    email: str
+
+class RefreshRequest(BaseModel):
+    refresh_token: str
+
+class TokenData(BaseModel):
+    user_id: Optional[str] = None
+    token_type: Optional[str] = None
+
+# ─── Password helpers (bcrypt direct — no passlib) ────────────────────────────
+def hash_password(password: str) -> str:
+    return _bcrypt.hashpw(password.encode("utf-8"), _bcrypt.gensalt(rounds=12)).decode("utf-8")
+
+def verify_password(plain: str, hashed: str) -> bool:
+    try:
+        return _bcrypt.checkpw(plain.encode("utf-8"), hashed.encode("utf-8"))
+    except Exception:
+        return False
+
+# ─── JWT helpers ──────────────────────────────────────────────────────────────
+def create_token(data: dict, expires_delta: timedelta) -> str:
+    payload = data.copy()
+    payload["exp"] = datetime.utcnow() + expires_delta
+    return jwt.encode(payload, SECRET_KEY, algorithm=ALGORITHM)
+
+def create_access_token(user_id: str) -> str:
+    return create_token(
+        {"sub": user_id, "type": "access"},
+        timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES),
+    )
+
+def create_refresh_token(user_id: str) -> str:
+    return create_token(
+        {"sub": user_id, "type": "refresh"},
+        timedelta(days=REFRESH_TOKEN_EXPIRE_DAYS),
+    )
+
+def decode_token(token: str) -> TokenData:
+    try:
+        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
+        user_id: str = payload.get("sub")
+        token_type: str = payload.get("type")
+        if not user_id:
+            raise HTTPException(status_code=401, detail="Invalid token payload")
+        return TokenData(user_id=user_id, token_type=token_type)
+    except JWTError:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Token expired or invalid",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+# ─── Auth dependencies ────────────────────────────────────────────────────────
+def get_current_user(
+    token: Optional[str] = Depends(oauth2_scheme),
+    db: Session = Depends(get_db),
+) -> User:
+    if not token:
+        raise HTTPException(status_code=401, detail="Not authenticated")
+    token_data = decode_token(token)
+    if token_data.token_type != "access":
+        raise HTTPException(status_code=401, detail="Invalid token type")
+    user = db.query(User).filter(User.id == token_data.user_id).first()
+    if not user:
+        raise HTTPException(status_code=401, detail="User not found")
+    return user
+
+def get_current_user_optional(
+    token: Optional[str] = Depends(oauth2_scheme),
+    db: Session = Depends(get_db),
+) -> Optional[User]:
+    if not token:
+        return None
+    try:
+        return get_current_user(token, db)
+    except HTTPException:
+        return None
+
+# ─── Routes ───────────────────────────────────────────────────────────────────
+@router.post("/register", response_model=LoginResponse, status_code=201)
+def register(req: RegisterRequest, db: Session = Depends(get_db)):
+    existing = db.query(User).filter(User.email == req.email).first()
+    if existing:
+        raise HTTPException(status_code=409, detail="Email already registered")
+
+    user = User(
+        id=generate_uuid(),
+        email=req.email,
+        password_hash=hash_password(req.password),
+        profile_data={"name": req.name},
+        financial_personality="Balanced",
+    )
+    db.add(user)
+    db.commit()
+    db.refresh(user)
+
+    return LoginResponse(
+        access_token=create_access_token(user.id),
+        refresh_token=create_refresh_token(user.id),
+        user_id=user.id,
+        name=req.name,
+        email=user.email,
+    )
+
+@router.post("/login", response_model=LoginResponse)
+def login(form: OAuth2PasswordRequestForm = Depends(), db: Session = Depends(get_db)):
+    user = db.query(User).filter(User.email == form.username).first()
+    if not user or not verify_password(form.password, user.password_hash):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Incorrect email or password",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    return LoginResponse(
+        access_token=create_access_token(user.id),
+        refresh_token=create_refresh_token(user.id),
+        user_id=user.id,
+        name=user.profile_data.get("name", "User"),
+        email=user.email,
+    )
+
+@router.post("/refresh")
+def refresh_token(req: RefreshRequest, db: Session = Depends(get_db)):
+    token_data = decode_token(req.refresh_token)
+    if token_data.token_type != "refresh":
+        raise HTTPException(status_code=401, detail="Invalid refresh token")
+    user = db.query(User).filter(User.id == token_data.user_id).first()
+    if not user:
+        raise HTTPException(status_code=401, detail="User not found")
+    return {
+        "access_token": create_access_token(user.id),
+        "token_type": "bearer",
+    }
+
+@router.get("/me")
+def get_me(current_user: User = Depends(get_current_user)):
+    return {
+        "user_id": current_user.id,
+        "email": current_user.email,
+        "name": current_user.profile_data.get("name", "User"),
+        "financial_personality": current_user.financial_personality,
+    }
+
+@router.post("/logout")
+def logout():
+    # Stateless JWT — client drops the token.
+    # Production: add token to a Redis blacklist here.
+    return {"message": "Logged out successfully"}

backend/app/dashboard/router.py

@@ -0,0 +1,189 @@
+"""
+Dashboard router — aggregated data for the main dashboard page.
+Returns balances, recent transactions, spending breakdown, and AI briefing.
+"""
+from typing import Optional
+from fastapi import APIRouter, Depends
+from sqlalchemy.orm import Session
+from sqlalchemy import func, desc
+from datetime import datetime, timedelta
+
+from app.database.database import get_db
+from app.database.models import User, Account, Transaction, AnalyticsSnapshot
+from app.middleware.cache import cache
+from app.ai.fraud import get_user_fraud_alerts
+from collections import defaultdict
+
+router = APIRouter(prefix="/api/dashboard", tags=["Dashboard"])
+
+def _resolve_user(db: Session, user_id: Optional[str]) -> str:
+    if user_id:
+        return user_id
+    user = db.query(User).first()
+    if not user:
+        from fastapi import HTTPException
+        raise HTTPException(status_code=404, detail="No users found. Seed the database first.")
+    return user.id
+
+@router.get("/overview")
+def get_dashboard_overview(user_id: Optional[str] = None, db: Session = Depends(get_db)):
+    """
+    Returns all data needed for the main dashboard in a single request:
+    - account balances
+    - monthly income/expense totals
+    - recent transactions (last 10)
+    - spending by category (current month)
+    - financial health score
+    - AI daily briefing (cached 1h)
+    - fraud alert count
+    """
+    uid = _resolve_user(db, user_id)
+    cache_key = f"dashboard:overview:{uid}"
+    cached = cache.get(cache_key)
+    if cached:
+        return cached
+
+    # ── Accounts & balances ──────────────────────────────────────────────────
+    accounts = db.query(Account).filter(Account.user_id == uid).all()
+    total_balance = sum(a.balance for a in accounts)
+    account_list = [
+        {"id": a.id, "type": a.type, "balance": a.balance, "currency": a.currency}
+        for a in accounts
+    ]
+
+    # ── Current month date range ─────────────────────────────────────────────
+    now = datetime.utcnow()
+    month_start = now.replace(day=1, hour=0, minute=0, second=0, microsecond=0)
+
+    # ── Transactions this month (lightweight) ───────────────────────────────
+    account_ids = [a.id for a in accounts]
+    monthly_raw = (
+        db.query(Transaction.type, Transaction.amount, Transaction.category)
+        .filter(
+            Transaction.account_id.in_(account_ids),
+            Transaction.timestamp >= month_start,
+        )
+        .all()
+    )
+
+    monthly_income = sum(amt for t_type, amt, _ in monthly_raw if t_type == "credit")
+    monthly_expenses = sum(abs(amt) for t_type, amt, _ in monthly_raw if t_type == "debit")
+    savings_rate = round((monthly_income - monthly_expenses) / monthly_income * 100, 1) if monthly_income > 0 else 0.0
+
+    # ── Spending by category ─────────────────────────────────────────────────
+    category_totals: dict = {}
+    for t_type, amt, cat in monthly_raw:
+        if t_type == "debit" and cat:
+            category_totals[cat] = category_totals.get(cat, 0) + abs(amt)
+
+    spending_by_category = [
+        {"name": cat, "value": round(total, 2)}
+        for cat, total in sorted(category_totals.items(), key=lambda x: -x[1])
+    ]
+
+    # ── Recent transactions (last 10) ────────────────────────────────────────
+    recent_txns = (
+        db.query(Transaction)
+        .filter(Transaction.account_id.in_(account_ids))
+        .order_by(desc(Transaction.timestamp))
+        .limit(10)
+        .all()
+    )
+    recent_list = [
+        {
+            "id": t.id,
+            "merchant": t.merchant or "Unknown",
+            "category": t.category or "Other",
+            "amount": t.amount if t.type == "credit" else -abs(t.amount),
+            "type": t.type,
+            "timestamp": t.timestamp.isoformat() if t.timestamp else None,
+        }
+        for t in recent_txns
+    ]
+
+    # ── 6-month cash flow trend (lightweight column-only query) ─────────────
+    six_months_ago = now - timedelta(days=180)
+    raw_6m = (
+        db.query(
+            Transaction.type,
+            Transaction.amount,
+            Transaction.timestamp,
+        )
+        .filter(
+            Transaction.account_id.in_(account_ids),
+            Transaction.timestamp >= six_months_ago,
+        )
+        .all()
+    )
+
+    # Group by month label in Python
+    month_buckets: dict = defaultdict(lambda: {"income": 0.0, "expenses": 0.0})
+    for t_type, t_amount, t_ts in raw_6m:
+        if t_ts:
+            label = t_ts.strftime("%b")
+            if t_type == "credit":
+                month_buckets[label]["income"] += t_amount
+            else:
+                month_buckets[label]["expenses"] += abs(t_amount)
+
+    # Build ordered list for last 6 months
+    cash_flow = []
+    for i in range(5, -1, -1):
+        m_date = (now.replace(day=1) - timedelta(days=i * 30))
+        label = m_date.strftime("%b")
+        inc = round(month_buckets[label]["income"], 2)
+        exp = round(month_buckets[label]["expenses"], 2)
+        cash_flow.append({
+            "month": label,
+            "income": inc,
+            "expenses": exp,
+            "savings": round(max(inc - exp, 0), 2),
+        })
+
+    # ── Financial health score (from cache only — never block on AI) ────────────
+    score_data = {}
+    health_score = 0.0
+    try:
+        score_cache_key = f"ai:coaching:score:{uid}"
+        score_data = cache.get(score_cache_key) or {}
+        health_score = score_data.get("overall_score", 0.0)
+    except Exception:
+        pass
+
+    # ── Fraud alerts (cached separately) ────────────────────────────────────
+    fraud_count = 0
+    try:
+        fraud_cache_key = f"dashboard:fraud:{uid}"
+        cached_fraud = cache.get(fraud_cache_key)
+        if cached_fraud is not None:
+            fraud_count = cached_fraud
+        else:
+            fraud_data = get_user_fraud_alerts(db, uid)
+            fraud_count = len(fraud_data.get("alerts", []))
+            cache.set(fraud_cache_key, fraud_count, ttl=300)  # 5-min cache
+    except Exception:
+        pass
+
+    # ── AI briefing (from cache only — never block on AI) ────────────────────
+    briefing_key = f"ai:coaching:briefing:{uid}"
+    briefing = cache.get(briefing_key) or {
+        "summary": "Run /api/ai/coaching/briefing to generate your AI daily briefing.",
+        "briefing": None,
+    }
+
+    result = {
+        "total_balance": round(total_balance, 2),
+        "accounts": account_list,
+        "monthly_income": round(monthly_income, 2),
+        "monthly_expenses": round(monthly_expenses, 2),
+        "savings_rate": savings_rate,
+        "spending_by_category": spending_by_category,
+        "recent_transactions": recent_list,
+        "cash_flow": cash_flow,
+        "health_score": round(health_score, 1),
+        "fraud_alert_count": fraud_count,
+        "ai_briefing": briefing,
+    }
+
+    cache.set(cache_key, result, ttl=120)  # 2-minute cache
+    return result

backend/app/database/database.py

@@ -0,0 +1,42 @@
+from sqlalchemy import create_engine
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.orm import sessionmaker
+from sqlalchemy.exc import OperationalError
+import os
+
+# Read database URL from environment or fallback to docker-compose default
+SQLALCHEMY_DATABASE_URL = os.getenv("DATABASE_URL", "postgresql://admin:adminpassword@localhost:5432/bankbot")
+USE_SQLITE = os.getenv("USE_SQLITE", "false").lower() in ("true", "1", "yes")
+
+BASE_DIR = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+sqlite_db_path = os.path.join(BASE_DIR, "bankbot.db")
+
+if USE_SQLITE:
+    SQLALCHEMY_DATABASE_URL = f"sqlite:///{sqlite_db_path}"
+
+connect_args = {}
+if "sqlite" in SQLALCHEMY_DATABASE_URL:
+    connect_args = {"check_same_thread": False}
+
+try:
+    engine = create_engine(SQLALCHEMY_DATABASE_URL, connect_args=connect_args)
+    # Test connection
+    with engine.connect() as conn:
+        pass
+except (OperationalError, Exception) as e:
+    print(f"Database connection to {SQLALCHEMY_DATABASE_URL} failed: {e}")
+    print(f"Falling back to SQLite database at sqlite:///{sqlite_db_path}...")
+    SQLALCHEMY_DATABASE_URL = f"sqlite:///{sqlite_db_path}"
+    connect_args = {"check_same_thread": False}
+    engine = create_engine(SQLALCHEMY_DATABASE_URL, connect_args=connect_args)
+
+SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+
+Base = declarative_base()
+
+def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()

backend/app/database/models.py

@@ -0,0 +1,147 @@
+from sqlalchemy import Column, Integer, String, Float, Boolean, DateTime, ForeignKey, Text, JSON
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+from app.database.database import Base
+import uuid
+
+def generate_uuid():
+    return str(uuid.uuid4())
+
+class User(Base):
+    __tablename__ = "users"
+
+    id = Column(String, primary_key=True, index=True, default=generate_uuid)
+    email = Column(String, unique=True, index=True, nullable=False)
+    password_hash = Column(String, nullable=False)
+    profile_data = Column(JSON, default={})
+    financial_personality = Column(String, default="Unknown")
+    ai_personalization_settings = Column(JSON, default={})
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+    updated_at = Column(DateTime(timezone=True), onupdate=func.now())
+
+    accounts = relationship("Account", back_populates="user")
+    subscriptions = relationship("Subscription", back_populates="user")
+    goals = relationship("Goal", back_populates="user")
+    investments = relationship("Investment", back_populates="user")
+    ai_insights = relationship("AIInsight", back_populates="user")
+    notifications = relationship("Notification", back_populates="user")
+    analytics_snapshots = relationship("AnalyticsSnapshot", back_populates="user")
+
+class Account(Base):
+    __tablename__ = "accounts"
+
+    id = Column(String, primary_key=True, index=True, default=generate_uuid)
+    user_id = Column(String, ForeignKey("users.id"), nullable=False)
+    type = Column(String, nullable=False) # e.g. checking, savings
+    balance = Column(Float, default=0.0)
+    currency = Column(String, default="USD")
+    status = Column(String, default="active")
+
+    user = relationship("User", back_populates="accounts")
+    transactions = relationship("Transaction", back_populates="account")
+
+class Transaction(Base):
+    __tablename__ = "transactions"
+
+    id = Column(String, primary_key=True, index=True, default=generate_uuid)
+    account_id = Column(String, ForeignKey("accounts.id"), nullable=False)
+    amount = Column(Float, nullable=False)
+    type = Column(String, nullable=False) # credit, debit
+    category = Column(String)
+    timestamp = Column(DateTime(timezone=True), server_default=func.now())
+    merchant = Column(String)
+    tags = Column(JSON, default=[])
+    ai_generated_metadata = Column(JSON, default={})
+    spending_emotion_label = Column(String)
+
+    account = relationship("Account", back_populates="transactions")
+    fraud_log = relationship("FraudLog", back_populates="transaction", uselist=False)
+
+class Subscription(Base):
+    __tablename__ = "subscriptions"
+
+    id = Column(String, primary_key=True, index=True, default=generate_uuid)
+    user_id = Column(String, ForeignKey("users.id"), nullable=False)
+    merchant = Column(String, nullable=False)
+    amount = Column(Float, nullable=False)
+    billing_cycle = Column(String, nullable=False) # monthly, yearly
+    active = Column(Boolean, default=True)
+    ai_usage_detection = Column(JSON, default={})
+
+    user = relationship("User", back_populates="subscriptions")
+
+class Goal(Base):
+    __tablename__ = "goals"
+
+    id = Column(String, primary_key=True, index=True, default=generate_uuid)
+    user_id = Column(String, ForeignKey("users.id"), nullable=False)
+    title = Column(String, nullable=False)
+    target_amount = Column(Float, nullable=False)
+    current_amount = Column(Float, default=0.0)
+    target_date = Column(DateTime(timezone=True))
+    ai_generated_plan = Column(JSON, default={})
+
+    user = relationship("User", back_populates="goals")
+
+class Investment(Base):
+    __tablename__ = "investments"
+
+    id = Column(String, primary_key=True, index=True, default=generate_uuid)
+    user_id = Column(String, ForeignKey("users.id"), nullable=False)
+    asset_name = Column(String, nullable=False)
+    type = Column(String, nullable=False) # stock, crypto, mutual_fund
+    amount_invested = Column(Float, default=0.0)
+    current_value = Column(Float, default=0.0)
+    portfolio_allocation = Column(Float, default=0.0)
+    ai_risk_analysis = Column(JSON, default={})
+
+    user = relationship("User", back_populates="investments")
+
+class AIInsight(Base):
+    __tablename__ = "ai_insights"
+
+    id = Column(String, primary_key=True, index=True, default=generate_uuid)
+    user_id = Column(String, ForeignKey("users.id"), nullable=False)
+    type = Column(String, nullable=False) # recommendation, briefing, cashflow
+    content = Column(Text, nullable=False)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+
+    user = relationship("User", back_populates="ai_insights")
+
+class FraudLog(Base):
+    __tablename__ = "fraud_logs"
+
+    id = Column(String, primary_key=True, index=True, default=generate_uuid)
+    transaction_id = Column(String, ForeignKey("transactions.id"), nullable=False)
+    risk_score = Column(Float, nullable=False)
+    suspicious_activity_details = Column(Text)
+    status = Column(String, default="pending") # pending, resolved, false_positive
+
+    transaction = relationship("Transaction", back_populates="fraud_log")
+
+class Notification(Base):
+    __tablename__ = "notifications"
+
+    id = Column(String, primary_key=True, index=True, default=generate_uuid)
+    user_id = Column(String, ForeignKey("users.id"), nullable=False)
+    title = Column(String, nullable=False)
+    message = Column(Text, nullable=False)
+    type = Column(String, nullable=False) # alert, insight, warning
+    read_status = Column(Boolean, default=False)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+
+    user = relationship("User", back_populates="notifications")
+
+class AnalyticsSnapshot(Base):
+    __tablename__ = "analytics_snapshots"
+
+    id = Column(String, primary_key=True, index=True, default=generate_uuid)
+    user_id = Column(String, ForeignKey("users.id"), nullable=False)
+    date = Column(DateTime(timezone=True), nullable=False)
+    total_balance = Column(Float, default=0.0)
+    total_spending = Column(Float, default=0.0)
+    total_savings = Column(Float, default=0.0)
+    financial_score = Column(Float, default=0.0)
+    trends_json = Column(JSON, default={})
+
+    user = relationship("User", back_populates="analytics_snapshots")

backend/app/main.py

@@ -0,0 +1,171 @@
+"""
+BankBot FastAPI — production entry point.
+Phase 7: structured logging, metrics, security headers, rate limiting.
+"""
+import json
+import os
+import time
+from collections import defaultdict
+
+from fastapi import FastAPI, Request, Response
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+
+from app.database.database import engine, Base
+import app.database.models  # noqa: F401
+
+# ─── Routers ──────────────────────────────────────────────────────────────────
+from app.ai.router          import router as ai_router
+from app.websocket.router   import router as ws_router
+from app.auth.router        import router as auth_router
+from app.dashboard.router   import router as dashboard_router
+from app.notifications.router import router as notifications_router
+from app.transactions.router  import router as transactions_router
+
+# ─── Observability ────────────────────────────────────────────────────────────
+from app.middleware.logging import RequestLoggingMiddleware, metrics, api_logger
+
+# ─── App ──────────────────────────────────────────────────────────────────────
+app = FastAPI(
+    title="BankBot AI API",
+    description="Production-grade AI-powered financial platform",
+    version="2.0.0",
+    docs_url="/docs",
+    redoc_url="/redoc",
+)
+
+# ─── CORS ─────────────────────────────────────────────────────────────────────
+_raw = os.environ.get("BACKEND_CORS_ORIGINS", '["http://localhost:3000","http://localhost:7860"]')
+try:
+    allowed_origins = json.loads(_raw)
+except Exception:
+    allowed_origins = ["http://localhost:3000", "http://localhost:7860"]
+
+# In HF Spaces, the Space URL is dynamic — allow all *.hf.space origins
+# by using allow_origin_regex as a fallback
+HF_SPACE_PATTERN = r"https://.*\.hf\.space"
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=allowed_origins,
+    allow_origin_regex=HF_SPACE_PATTERN,
+    allow_credentials=True,
+    allow_methods=["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+    allow_headers=["Authorization", "Content-Type", "X-Request-ID"],
+    expose_headers=["X-Request-ID", "X-Process-Time"],
+)
+
+# ─── Request logging ──────────────────────────────────────────────────────────
+app.add_middleware(RequestLoggingMiddleware)
+
+# ─── Security headers ─────────────────────────────────────────────────────────
+@app.middleware("http")
+async def security_headers(request: Request, call_next):
+    response: Response = await call_next(request)
+    response.headers["X-Content-Type-Options"] = "nosniff"
+    response.headers["X-Frame-Options"] = "DENY"
+    response.headers["X-XSS-Protection"] = "1; mode=block"
+    response.headers["Referrer-Policy"] = "strict-origin-when-cross-origin"
+    response.headers["Permissions-Policy"] = "camera=(), microphone=(), geolocation=()"
+    return response
+
+# ─── Process-time header ──────────────────────────────────────────────────────
+@app.middleware("http")
+async def process_time_header(request: Request, call_next):
+    t = time.time()
+    response = await call_next(request)
+    response.headers["X-Process-Time"] = f"{(time.time()-t)*1000:.1f}ms"
+    return response
+
+# ─── Rate limiter ─────────────────────────────────────────────────────────────
+_rate_store: dict = defaultdict(list)
+RATE_LIMIT  = 120
+RATE_WINDOW = 60
+
+@app.middleware("http")
+async def rate_limit(request: Request, call_next):
+    skip = request.url.path in ("/health", "/") or \
+           "websocket" in request.headers.get("upgrade", "").lower()
+    if skip:
+        return await call_next(request)
+
+    ip  = request.client.host if request.client else "unknown"
+    now = time.time()
+    _rate_store[ip] = [t for t in _rate_store[ip] if t > now - RATE_WINDOW]
+
+    if len(_rate_store[ip]) >= RATE_LIMIT:
+        metrics.record_error(request.url.path, 429, "rate_limited")
+        return JSONResponse(
+            status_code=429,
+            content={"detail": "Too many requests. Please slow down."},
+            headers={"Retry-After": str(RATE_WINDOW)},
+        )
+    _rate_store[ip].append(now)
+    return await call_next(request)
+
+# ─── Startup ──────────────────────────────────────────────────────────────────
+@app.on_event("startup")
+def startup():
+    api_logger.info("BankBot API starting", extra={"version": "2.0.0"})
+    Base.metadata.create_all(bind=engine)
+    api_logger.info("Database tables ready")
+
+    # Log active backends
+    from app.ai.ollama_integration import OPENAI_API_KEY, GROQ_API_KEY, has_active_ai_backend
+    from app.middleware.cache import cache
+    from app.database.database import SQLALCHEMY_DATABASE_URL
+
+    ai_backend = "openai" if OPENAI_API_KEY else ("groq" if GROQ_API_KEY else "ollama")
+    api_logger.info("Startup diagnostics", extra={
+        "ai_backend": ai_backend,
+        "ai_available": has_active_ai_backend(),
+        "db_type": "sqlite" if "sqlite" in SQLALCHEMY_DATABASE_URL else "postgresql",
+        "cache_type": "redis" if cache.use_redis else "memory",
+    })
+
+# ─── Routers ──────────────────────────────────────────────────────────────────
+app.include_router(auth_router)
+app.include_router(ai_router)
+app.include_router(ws_router)
+app.include_router(dashboard_router)
+app.include_router(notifications_router)
+app.include_router(transactions_router)
+
+# ─── Core endpoints ───────────────────────────────────────────────────────────
+@app.get("/", tags=["Core"])
+def root():
+    return {"message": "BankBot AI API v2.0", "status": "operational", "docs": "/docs"}
+
+@app.get("/health", tags=["Core"])
+def health():
+    from app.middleware.cache import cache
+    from app.database.database import SQLALCHEMY_DATABASE_URL
+    return {
+        "status": "healthy",
+        "timestamp": time.time(),
+        "db": "sqlite" if "sqlite" in SQLALCHEMY_DATABASE_URL else "postgresql",
+        "cache": "redis" if cache.use_redis else "memory",
+        "uptime_s": round(time.time() - metrics.start_time, 0),
+    }
+
+@app.get("/api/status", tags=["Core"])
+def api_status():
+    from app.ai.ollama_integration import has_active_ai_backend, OPENAI_API_KEY, GROQ_API_KEY
+    from app.middleware.cache import cache
+    from app.database.database import SQLALCHEMY_DATABASE_URL
+    ai = "openai" if OPENAI_API_KEY else ("groq" if GROQ_API_KEY else "ollama")
+    return {
+        "ai_backend": ai,
+        "ai_available": has_active_ai_backend(),
+        "db_type": "sqlite" if "sqlite" in SQLALCHEMY_DATABASE_URL else "postgresql",
+        "cache_type": "redis" if cache.use_redis else "memory",
+        "version": "2.0.0",
+    }
+
+@app.get("/api/metrics", tags=["Observability"])
+def get_metrics():
+    """
+    Live observability dashboard — request counts, AI latency,
+    cache hit ratio, WebSocket stats, recent errors.
+    """
+    return metrics.summary()

backend/app/middleware/cache.py

@@ -0,0 +1,86 @@
+import os
+import json
+import time
+from threading import Lock
+
+try:
+    import redis
+except ImportError:
+    redis = None
+
+class MemoryCache:
+    def __init__(self):
+        self._cache = {}
+        self._lock = Lock()
+
+    def get(self, key):
+        with self._lock:
+            if key not in self._cache:
+                return None
+            val, expiry = self._cache[key]
+            if expiry is not None and time.time() > expiry:
+                del self._cache[key]
+                return None
+            return val
+
+    def set(self, key, value, ttl=None):
+        with self._lock:
+            expiry = time.time() + ttl if ttl is not None else None
+            self._cache[key] = (value, expiry)
+
+    def delete(self, key):
+        with self._lock:
+            if key in self._cache:
+                del self._cache[key]
+
+class CacheManager:
+    def __init__(self):
+        self.redis_url = os.getenv("REDIS_URL", "redis://localhost:6379/0")
+        self.redis_client = None
+        self.use_redis = False
+        
+        if redis is not None:
+            try:
+                self.redis_client = redis.Redis.from_url(self.redis_url, socket_timeout=1.0)
+                # Test connection
+                self.redis_client.ping()
+                self.use_redis = True
+                print("Connected to Redis successfully.")
+            except Exception as e:
+                print(f"Redis connection failed ({e}). Falling back to in-memory cache.")
+        else:
+            print("Redis library not installed. Falling back to in-memory cache.")
+            
+        self.memory_cache = MemoryCache()
+
+    def get(self, key: str):
+        if self.use_redis:
+            try:
+                val = self.redis_client.get(key)
+                if val:
+                    return json.loads(val.decode('utf-8'))
+            except Exception as e:
+                # Fallback to memory on Redis error during operation
+                print(f"Redis get failed ({e}). Using memory cache fallback.")
+        return self.memory_cache.get(key)
+
+    def set(self, key: str, value, ttl: int = None):
+        if self.use_redis:
+            try:
+                self.redis_client.set(key, json.dumps(value), ex=ttl)
+                return
+            except Exception as e:
+                print(f"Redis set failed ({e}). Using memory cache fallback.")
+        self.memory_cache.set(key, value, ttl)
+
+    def delete(self, key: str):
+        if self.use_redis:
+            try:
+                self.redis_client.delete(key)
+                return
+            except Exception as e:
+                print(f"Redis delete failed ({e}). Using memory cache fallback.")
+        self.memory_cache.delete(key)
+
+# Global cache instance
+cache = CacheManager()

backend/app/middleware/logging.py

@@ -0,0 +1,184 @@
+"""
+Structured logging middleware — JSON logs with request tracing,
+timing, AI provider health, cache hit ratios, and WebSocket events.
+"""
+import json
+import logging
+import time
+import uuid
+from collections import defaultdict, deque
+from datetime import datetime
+from typing import Callable
+
+from fastapi import Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware
+
+# ─── Structured JSON logger ───────────────────────────────────────────────────
+class JSONFormatter(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        log = {
+            "ts": datetime.utcnow().isoformat() + "Z",
+            "level": record.levelname,
+            "logger": record.name,
+            "msg": record.getMessage(),
+        }
+        if hasattr(record, "extra"):
+            log.update(record.extra)
+        if record.exc_info:
+            log["exc"] = self.formatException(record.exc_info)
+        return json.dumps(log)
+
+def get_logger(name: str) -> logging.Logger:
+    logger = logging.getLogger(name)
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        handler.setFormatter(JSONFormatter())
+        logger.addHandler(handler)
+        logger.setLevel(logging.INFO)
+        logger.propagate = False
+    return logger
+
+api_logger = get_logger("bankbot.api")
+ai_logger  = get_logger("bankbot.ai")
+ws_logger  = get_logger("bankbot.ws")
+db_logger  = get_logger("bankbot.db")
+
+# ─── In-process metrics store ─────────────────────────────────────────────────
+class MetricsStore:
+    """Thread-safe in-memory metrics — no external dependency."""
+
+    def __init__(self):
+        self.request_count: int = 0
+        self.error_count: int = 0
+        self.auth_failures: int = 0
+        self.ws_connects: int = 0
+        self.ws_reconnects: int = 0
+        self.ai_calls: dict = defaultdict(int)          # provider → count
+        self.ai_errors: dict = defaultdict(int)         # provider → errors
+        self.ai_latencies: dict = defaultdict(list)     # provider → [ms]
+        self.ai_fallbacks: int = 0
+        self.cache_hits: int = 0
+        self.cache_misses: int = 0
+        self.route_timings: dict = defaultdict(list)    # path → [ms]
+        self._recent_errors: deque = deque(maxlen=50)   # last 50 errors
+        self.start_time: float = time.time()
+
+    # ── AI tracking ──────────────────────────────────────────────────────────
+    def record_ai_call(self, provider: str, latency_ms: float, success: bool):
+        self.ai_calls[provider] += 1
+        self.ai_latencies[provider].append(latency_ms)
+        if len(self.ai_latencies[provider]) > 200:
+            self.ai_latencies[provider] = self.ai_latencies[provider][-200:]
+        if not success:
+            self.ai_errors[provider] += 1
+
+    def record_ai_fallback(self):
+        self.ai_fallbacks += 1
+
+    # ── Cache tracking ────────────────────────────────────────────────────────
+    def record_cache_hit(self):
+        self.cache_hits += 1
+
+    def record_cache_miss(self):
+        self.cache_misses += 1
+
+    # ── Error tracking ────────────────────────────────────────────────────────
+    def record_error(self, path: str, status: int, detail: str):
+        self._recent_errors.append({
+            "ts": datetime.utcnow().isoformat() + "Z",
+            "path": path,
+            "status": status,
+            "detail": detail[:200],
+        })
+        self.error_count += 1
+        if status == 401:
+            self.auth_failures += 1
+
+    # ── Summary ───────────────────────────────────────────────────────────────
+    def summary(self) -> dict:
+        uptime = time.time() - self.start_time
+        cache_total = self.cache_hits + self.cache_misses
+        cache_ratio = round(self.cache_hits / cache_total * 100, 1) if cache_total else 0
+
+        ai_summary = {}
+        for provider in set(list(self.ai_calls.keys()) + list(self.ai_errors.keys())):
+            lats = self.ai_latencies.get(provider, [])
+            ai_summary[provider] = {
+                "calls": self.ai_calls[provider],
+                "errors": self.ai_errors[provider],
+                "avg_latency_ms": round(sum(lats) / len(lats), 1) if lats else 0,
+                "p95_latency_ms": round(sorted(lats)[int(len(lats) * 0.95)], 1) if len(lats) >= 20 else None,
+            }
+
+        slow_routes = {}
+        for path, times in self.route_timings.items():
+            if times:
+                slow_routes[path] = {
+                    "calls": len(times),
+                    "avg_ms": round(sum(times) / len(times), 1),
+                    "max_ms": round(max(times), 1),
+                }
+
+        return {
+            "uptime_seconds": round(uptime, 0),
+            "requests": {
+                "total": self.request_count,
+                "errors": self.error_count,
+                "auth_failures": self.auth_failures,
+                "error_rate_pct": round(self.error_count / max(self.request_count, 1) * 100, 2),
+            },
+            "websocket": {
+                "total_connects": self.ws_connects,
+                "reconnects": self.ws_reconnects,
+            },
+            "ai": {
+                "fallbacks": self.ai_fallbacks,
+                "by_provider": ai_summary,
+            },
+            "cache": {
+                "hits": self.cache_hits,
+                "misses": self.cache_misses,
+                "hit_ratio_pct": cache_ratio,
+            },
+            "route_timings": dict(sorted(slow_routes.items(), key=lambda x: -x[1]["avg_ms"])[:10]),
+            "recent_errors": list(self._recent_errors)[-10:],
+        }
+
+metrics = MetricsStore()
+
+# ─── Request logging middleware ───────────────────────────────────────────────
+class RequestLoggingMiddleware(BaseHTTPMiddleware):
+    SKIP_PATHS = {"/health", "/openapi.json", "/docs", "/redoc", "/docs/oauth2-redirect"}
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        if request.url.path in self.SKIP_PATHS:
+            return await call_next(request)
+
+        request_id = str(uuid.uuid4())[:8]
+        start = time.time()
+        metrics.request_count += 1
+
+        response = await call_next(request)
+
+        elapsed_ms = (time.time() - start) * 1000
+        path = request.url.path
+        metrics.route_timings[path].append(elapsed_ms)
+        if len(metrics.route_timings[path]) > 500:
+            metrics.route_timings[path] = metrics.route_timings[path][-500:]
+
+        level = logging.WARNING if elapsed_ms > 2000 else logging.INFO
+        if response.status_code >= 400:
+            metrics.record_error(path, response.status_code, "")
+            level = logging.WARNING if response.status_code < 500 else logging.ERROR
+
+        api_logger.log(level, f"{request.method} {path}", extra={
+            "request_id": request_id,
+            "method": request.method,
+            "path": path,
+            "status": response.status_code,
+            "duration_ms": round(elapsed_ms, 1),
+            "ip": request.client.host if request.client else "unknown",
+        })
+
+        response.headers["X-Request-ID"] = request_id
+        return response

backend/app/notifications/router.py

@@ -0,0 +1,90 @@
+"""
+Notifications router — CRUD for user notifications with WebSocket push support.
+"""
+from typing import Optional
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.orm import Session
+from sqlalchemy import desc
+
+from app.database.database import get_db
+from app.database.models import Notification, User, generate_uuid
+from datetime import datetime
+
+router = APIRouter(prefix="/api/notifications", tags=["Notifications"])
+
+def _resolve_user(db: Session, user_id: Optional[str]) -> str:
+    if user_id:
+        return user_id
+    user = db.query(User).first()
+    if not user:
+        raise HTTPException(status_code=404, detail="No users found.")
+    return user.id
+
+@router.get("/")
+def get_notifications(user_id: Optional[str] = None, limit: int = 20, db: Session = Depends(get_db)):
+    uid = _resolve_user(db, user_id)
+    notifications = (
+        db.query(Notification)
+        .filter(Notification.user_id == uid)
+        .order_by(desc(Notification.created_at))
+        .limit(limit)
+        .all()
+    )
+    return {
+        "notifications": [
+            {
+                "id": n.id,
+                "title": n.title,
+                "message": n.message,
+                "type": n.type,
+                "read": n.read_status,
+                "created_at": n.created_at.isoformat() if n.created_at else None,
+            }
+            for n in notifications
+        ],
+        "unread_count": sum(1 for n in notifications if not n.read_status),
+    }
+
+@router.patch("/{notification_id}/read")
+def mark_notification_read(
+    notification_id: str,
+    user_id: Optional[str] = None,
+    db: Session = Depends(get_db)
+):
+    uid = _resolve_user(db, user_id)
+    notif = db.query(Notification).filter(
+        Notification.id == notification_id,
+        Notification.user_id == uid
+    ).first()
+    if not notif:
+        raise HTTPException(status_code=404, detail="Notification not found")
+    notif.read_status = True
+    db.commit()
+    return {"success": True}
+
+@router.patch("/read-all")
+def mark_all_read(user_id: Optional[str] = None, db: Session = Depends(get_db)):
+    uid = _resolve_user(db, user_id)
+    db.query(Notification).filter(
+        Notification.user_id == uid,
+        Notification.read_status == False
+    ).update({"read_status": True})
+    db.commit()
+    return {"success": True}
+
+@router.delete("/{notification_id}")
+def delete_notification(
+    notification_id: str,
+    user_id: Optional[str] = None,
+    db: Session = Depends(get_db)
+):
+    uid = _resolve_user(db, user_id)
+    notif = db.query(Notification).filter(
+        Notification.id == notification_id,
+        Notification.user_id == uid
+    ).first()
+    if not notif:
+        raise HTTPException(status_code=404, detail="Notification not found")
+    db.delete(notif)
+    db.commit()
+    return {"success": True}

backend/app/scripts/seed.py

@@ -0,0 +1,194 @@
+import os
+import sys
+import uuid
+import random
+from datetime import datetime, timedelta
+
+# Add parent directory to path so we can import from app
+sys.path.append(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
+
+from app.database.database import SessionLocal, engine, SQLALCHEMY_DATABASE_URL
+from app.database.models import (
+    Base, User, Account, Transaction, Subscription,
+    Goal, Investment, AIInsight, FraudLog, Notification, AnalyticsSnapshot
+)
+
+# Create tables
+Base.metadata.create_all(bind=engine)
+
+def seed_data():
+    db = SessionLocal()
+
+    print(f"Seeding into: {SQLALCHEMY_DATABASE_URL}")
+
+    # Check if we already have users
+    if db.query(User).count() > 0:
+        print("Database already seeded.")
+        db.close()
+        return
+
+    print("Seeding database...")
+
+    personas = ["Saver", "Investor", "Impulsive Spender", "Minimalist", "Risk Taker"]
+
+    merchants = ["Swiggy", "Amazon", "Netflix", "Uber", "Fuel", "Salary", "SIP",
+                 "Starbucks", "Apple", "Walmart"]
+    categories = ["Food", "Shopping", "Entertainment", "Transport", "Income",
+                  "Investment", "Groceries", "Tech", "Utilities"]
+
+    for persona in personas:
+        try:
+            user = User(
+                email=f"{persona.lower().replace(' ', '_')}@example.com",
+                password_hash="hashed_password",
+                profile_data={"name": f"{persona} User", "phone": "+1234567890"},
+                financial_personality=persona,
+                ai_personalization_settings={"theme": "dark", "notifications": "all"}
+            )
+            db.add(user)
+            db.flush()  # get user.id without committing
+
+            # ── Accounts ──────────────────────────────────────────────────────
+            checking = Account(
+                user_id=user.id, type="checking",
+                balance=random.uniform(1000.0, 10000.0), currency="USD"
+            )
+            savings = Account(
+                user_id=user.id, type="savings",
+                balance=random.uniform(5000.0, 50000.0), currency="USD"
+            )
+            db.add_all([checking, savings])
+            db.flush()
+
+            # ── Subscriptions ─────────────────────────────────────────────────
+            # Active subscription (high usage)
+            db.add(Subscription(
+                user_id=user.id, merchant="Netflix", amount=15.99,
+                billing_cycle="monthly", active=True,
+                ai_usage_detection={"usage_frequency": "high", "recommendation": "keep"}
+            ))
+            # Unused subscription — triggers unused detection in subscriptions.py
+            db.add(Subscription(
+                user_id=user.id, merchant="Spotify", amount=9.99,
+                billing_cycle="monthly", active=True,
+                ai_usage_detection={"usage_frequency": "low", "recommendation": "cancel"}
+            ))
+            # Duplicate subscription — triggers duplicate detection in subscriptions.py
+            # (second Netflix entry for the same user)
+            db.add(Subscription(
+                user_id=user.id, merchant="Netflix", amount=15.99,
+                billing_cycle="monthly", active=True,
+                ai_usage_detection={"usage_frequency": "medium", "recommendation": "review"}
+            ))
+
+            # ── Goals ─────────────────────────────────────────────────────────
+            db.add(Goal(
+                user_id=user.id, title="Emergency Fund",
+                target_amount=10000.0,
+                current_amount=random.uniform(1000.0, 5000.0),
+                target_date=datetime.utcnow() + timedelta(days=365),
+                ai_generated_plan={"monthly_saving_required": 500.0, "risk": "low"}
+            ))
+
+            # ── Investments ───────────────────────────────────────────────────
+            db.add(Investment(
+                user_id=user.id, asset_name="S&P 500", type="stock",
+                amount_invested=random.uniform(1000.0, 10000.0),
+                current_value=random.uniform(1100.0, 12000.0),
+                portfolio_allocation=50.0,
+                ai_risk_analysis={"risk_level": "medium", "recommendation": "hold"}
+            ))
+
+            # ── Transactions ──────────────────────────────────────────────────
+            start_date = datetime.utcnow() - timedelta(days=90)
+
+            # Monthly salary (3 months)
+            for i in range(3):
+                tx_date = start_date + timedelta(days=i * 30)
+                db.add(Transaction(
+                    account_id=checking.id, amount=5000.0, type="credit",
+                    category="Income", timestamp=tx_date, merchant="Salary",
+                    tags=["salary", "income"],
+                    ai_generated_metadata={"is_recurring": True, "confidence": 0.99},
+                    spending_emotion_label="neutral"
+                ))
+
+            # Regular expense transactions
+            for _ in range(30):
+                tx_date = start_date + timedelta(days=random.randint(0, 89))
+                amount = random.uniform(10.0, 500.0)
+                merchant = random.choice(merchants)
+
+                if merchant == "Salary":
+                    continue
+
+                # Persona-based spending adjustments
+                if user.financial_personality == "Saver" and amount > 200:
+                    amount = random.uniform(10.0, 100.0)
+                elif user.financial_personality == "Impulsive Spender":
+                    amount = random.uniform(50.0, 800.0)
+
+                tx = Transaction(
+                    account_id=checking.id, amount=amount, type="debit",
+                    category=random.choice(categories),
+                    timestamp=tx_date, merchant=merchant,
+                    tags=["expense"],
+                    ai_generated_metadata={"category_confidence": 0.9},
+                    spending_emotion_label=random.choice(["happy", "regret", "neutral", "essential"])
+                )
+                db.add(tx)
+                db.flush()
+
+                # Seed a fraud log for ~5% of transactions
+                if random.random() < 0.05:
+                    db.add(FraudLog(
+                        transaction_id=tx.id,
+                        risk_score=random.uniform(0.7, 0.99),
+                        suspicious_activity_details="Unusual location and high amount for this merchant.",
+                        status="pending"
+                    ))
+
+            # Late-night transaction — ensures behavior.py late-night detection fires
+            late_night_date = start_date + timedelta(days=random.randint(1, 80),
+                                                      hours=23, minutes=random.randint(0, 59))
+            db.add(Transaction(
+                account_id=checking.id,
+                amount=random.uniform(50.0, 300.0),
+                type="debit",
+                category="Entertainment",
+                timestamp=late_night_date,
+                merchant="Online Store",
+                tags=["late-night", "impulse"],
+                ai_generated_metadata={"category_confidence": 0.85},
+                spending_emotion_label="regret"
+            ))
+
+            # ── Supporting records ────────────────────────────────────────────
+            db.add(AIInsight(
+                user_id=user.id, type="cashflow",
+                content=f"You are spending 20% more on {random.choice(categories)} this month."
+            ))
+            db.add(Notification(
+                user_id=user.id, title="Weekly Summary",
+                message="Your weekly financial summary is ready.", type="insight"
+            ))
+            db.add(AnalyticsSnapshot(
+                user_id=user.id, date=datetime.utcnow(),
+                total_balance=checking.balance + savings.balance,
+                total_spending=2000.0, total_savings=3000.0,
+                financial_score=random.uniform(60.0, 95.0),
+                trends_json={"spending_trend": "down", "savings_trend": "up"}
+            ))
+
+            db.commit()
+            print(f"  ✓ Seeded user: {persona}")
+
+        except Exception as e:
+            db.rollback()
+            print(f"  ✗ Failed to seed user '{persona}': {e}")
+
+    db.close()
+    print("Database seeded successfully!")
+
+if __name__ == "__main__":
+    seed_data()

backend/app/scripts/seed_demo.py

@@ -0,0 +1,300 @@
+"""
+Demo seed script — creates a polished demo account (alex@bankbot.dev)
+with realistic financial data: transactions, goals, investments,
+subscriptions, notifications, and a fraud alert.
+
+Run: python app/scripts/seed_demo.py
+"""
+import os
+import sys
+import uuid
+import random
+from datetime import datetime, timedelta
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
+
+import bcrypt as _bcrypt
+from app.database.database import SessionLocal, engine
+from app.database.models import (
+    Base, User, Account, Transaction, Subscription,
+    Goal, Investment, Notification, FraudLog
+)
+
+Base.metadata.create_all(bind=engine)
+
+DEMO_EMAIL    = "alex@bankbot.dev"
+DEMO_PASSWORD = "BankBot2026!"
+DEMO_NAME     = "Alex Doe"
+
+def hash_pw(pw: str) -> str:
+    return _bcrypt.hashpw(pw.encode(), _bcrypt.gensalt(rounds=12)).decode()
+
+def uid() -> str:
+    return str(uuid.uuid4())
+
+def seed():
+    db = SessionLocal()
+    try:
+        # ── Remove existing demo user ────────────────────────────────────────
+        existing = db.query(User).filter(User.email == DEMO_EMAIL).first()
+        if existing:
+            db.delete(existing)
+            db.commit()
+            print(f"Removed existing demo user: {DEMO_EMAIL}")
+
+        # ── Create demo user ─────────────────────────────────────────────────
+        user = User(
+            id=uid(),
+            email=DEMO_EMAIL,
+            password_hash=hash_pw(DEMO_PASSWORD),
+            profile_data={
+                "name": DEMO_NAME,
+                "phone": "+1 (555) 012-3456",
+                "avatar": "AD",
+                "member_since": "2023-01-15",
+                "plan": "Premium",
+            },
+            financial_personality="Balanced Investor",
+            ai_personalization_settings={
+                "risk_tolerance": "moderate",
+                "investment_horizon": "long_term",
+                "notifications": "all",
+                "ai_tone": "analytical",
+            },
+        )
+        db.add(user)
+        db.flush()
+        print(f"Created demo user: {DEMO_EMAIL}")
+
+        # ── Accounts ─────────────────────────────────────────────────────────
+        checking = Account(id=uid(), user_id=user.id, type="checking",
+                           balance=12_847.32, currency="USD", status="active")
+        savings  = Account(id=uid(), user_id=user.id, type="savings",
+                           balance=28_450.00, currency="USD", status="active")
+        invest   = Account(id=uid(), user_id=user.id, type="investment",
+                           balance=18_340.50, currency="USD", status="active")
+        db.add_all([checking, savings, invest])
+        db.flush()
+        print("Created 3 accounts (checking $12,847 | savings $28,450 | investment $18,340)")
+
+        # ── Transactions — 6 months of realistic data ─────────────────────────
+        now = datetime.utcnow()
+        merchants = [
+            # (name, category, type, amount_range)
+            ("Salary Deposit",    "Income",        "credit", (4800, 5200)),
+            ("Freelance Payment", "Income",        "credit", (800,  2000)),
+            ("Whole Foods",       "Groceries",     "debit",  (45,   180)),
+            ("Trader Joe's",      "Groceries",     "debit",  (30,   120)),
+            ("Netflix",           "Entertainment", "debit",  (15,   16)),
+            ("Spotify",           "Entertainment", "debit",  (9,    10)),
+            ("Amazon",            "Shopping",      "debit",  (25,   250)),
+            ("Apple Store",       "Tech",          "debit",  (10,   200)),
+            ("Uber",              "Transport",     "debit",  (8,    45)),
+            ("Shell Gas",         "Transport",     "debit",  (40,   80)),
+            ("Starbucks",         "Food",          "debit",  (5,    18)),
+            ("Chipotle",          "Food",          "debit",  (10,   25)),
+            ("Planet Fitness",    "Health",        "debit",  (24,   25)),
+            ("CVS Pharmacy",      "Health",        "debit",  (12,   60)),
+            ("Con Edison",        "Utilities",     "debit",  (80,   140)),
+            ("Verizon",           "Utilities",     "debit",  (85,   90)),
+            ("Rent Payment",      "Housing",       "debit",  (1950, 1950)),
+            ("Dividend Income",   "Investment",    "credit", (120,  350)),
+            ("Restaurant",        "Food",          "debit",  (30,   90)),
+            ("Target",            "Shopping",      "debit",  (40,   150)),
+        ]
+
+        txns = []
+        for month_offset in range(6):
+            month_start = (now.replace(day=1) - timedelta(days=month_offset * 30))
+            # Salary on 1st
+            txns.append(Transaction(
+                id=uid(), account_id=checking.id,
+                amount=random.uniform(4800, 5200), type="credit",
+                category="Income", merchant="Salary Deposit",
+                timestamp=month_start + timedelta(hours=9),
+                tags=["recurring", "income"],
+            ))
+            # Rent on 3rd
+            txns.append(Transaction(
+                id=uid(), account_id=checking.id,
+                amount=1950.00, type="debit",
+                category="Housing", merchant="Rent Payment",
+                timestamp=month_start + timedelta(days=2, hours=10),
+                tags=["recurring", "housing"],
+            ))
+            # Random daily transactions
+            for _ in range(random.randint(18, 28)):
+                m = random.choice(merchants[2:])  # skip salary/rent
+                days_offset = random.randint(0, 28)
+                hours_offset = random.randint(7, 22)
+                txns.append(Transaction(
+                    id=uid(), account_id=checking.id,
+                    amount=round(random.uniform(*m[3]), 2),
+                    type=m[2], category=m[1], merchant=m[0],
+                    timestamp=month_start + timedelta(days=days_offset, hours=hours_offset),
+                    tags=[m[1].lower()],
+                ))
+
+        # One suspicious transaction for fraud demo
+        fraud_txn = Transaction(
+            id=uid(), account_id=checking.id,
+            amount=847.00, type="debit",
+            category="Shopping", merchant="Tech Store NYC",
+            timestamp=now - timedelta(hours=2),
+            tags=["flagged"],
+            spending_emotion_label="impulsive",
+        )
+        txns.append(fraud_txn)
+        db.add_all(txns)
+        db.flush()
+        print(f"Created {len(txns)} transactions across 6 months")
+
+        # ── Fraud log for the suspicious transaction ──────────────────────────
+        fraud_log = FraudLog(
+            id=uid(),
+            transaction_id=fraud_txn.id,
+            risk_score=0.78,
+            suspicious_activity_details=(
+                "Transaction amount ($847.00) is 3.2x above historical average. "
+                "Location anomaly: merchant in NYC, usual activity in Brooklyn. "
+                "Placed at 11:47 PM — outside normal spending hours."
+            ),
+            status="pending",
+        )
+        db.add(fraud_log)
+        print("Created fraud alert for demo transaction")
+
+        # ── Goals ─────────────────────────────────────────────────────────────
+        goals = [
+            Goal(id=uid(), user_id=user.id, title="Emergency Fund",
+                 target_amount=18_000, current_amount=14_200,
+                 target_date=now + timedelta(days=90),
+                 ai_generated_plan={"monthly_contribution": 1267, "months_remaining": 3}),
+            Goal(id=uid(), user_id=user.id, title="Europe Vacation",
+                 target_amount=5_000, current_amount=2_800,
+                 target_date=now + timedelta(days=180),
+                 ai_generated_plan={"monthly_contribution": 367, "months_remaining": 6}),
+            Goal(id=uid(), user_id=user.id, title="MacBook Pro",
+                 target_amount=2_500, current_amount=1_900,
+                 target_date=now + timedelta(days=45),
+                 ai_generated_plan={"monthly_contribution": 300, "months_remaining": 2}),
+            Goal(id=uid(), user_id=user.id, title="Down Payment Fund",
+                 target_amount=80_000, current_amount=28_450,
+                 target_date=now + timedelta(days=730),
+                 ai_generated_plan={"monthly_contribution": 2148, "months_remaining": 24}),
+        ]
+        db.add_all(goals)
+        print(f"Created {len(goals)} financial goals")
+
+        # ── Investments ───────────────────────────────────────────────────────
+        investments = [
+            Investment(id=uid(), user_id=user.id, asset_name="S&P 500 Index Fund",
+                       type="mutual_fund", amount_invested=8_000, current_value=9_840,
+                       portfolio_allocation=53.6,
+                       ai_risk_analysis={"risk": "moderate", "expected_return": "8-10%", "recommendation": "hold"}),
+            Investment(id=uid(), user_id=user.id, asset_name="Apple Inc (AAPL)",
+                       type="stock", amount_invested=3_000, current_value=3_720,
+                       portfolio_allocation=20.3,
+                       ai_risk_analysis={"risk": "moderate-high", "expected_return": "12-15%", "recommendation": "hold"}),
+            Investment(id=uid(), user_id=user.id, asset_name="Bitcoin (BTC)",
+                       type="crypto", amount_invested=2_500, current_value=2_980,
+                       portfolio_allocation=16.2,
+                       ai_risk_analysis={"risk": "high", "expected_return": "variable", "recommendation": "reduce_exposure"}),
+            Investment(id=uid(), user_id=user.id, asset_name="US Treasury Bonds",
+                       type="bond", amount_invested=1_800, current_value=1_800,
+                       portfolio_allocation=9.8,
+                       ai_risk_analysis={"risk": "low", "expected_return": "4.5%", "recommendation": "hold"}),
+        ]
+        db.add_all(investments)
+        print(f"Created {len(investments)} investments (total value: ${sum(i.current_value for i in investments):,.0f})")
+
+        # ── Subscriptions ─────────────────────────────────────────────────────
+        subscriptions = [
+            Subscription(id=uid(), user_id=user.id, merchant="Netflix",
+                         amount=15.99, billing_cycle="monthly", active=True,
+                         ai_usage_detection={"last_used": "2 days ago", "usage_frequency": "high"}),
+            Subscription(id=uid(), user_id=user.id, merchant="Spotify",
+                         amount=9.99, billing_cycle="monthly", active=True,
+                         ai_usage_detection={"last_used": "today", "usage_frequency": "daily"}),
+            Subscription(id=uid(), user_id=user.id, merchant="Adobe Creative Cloud",
+                         amount=54.99, billing_cycle="monthly", active=True,
+                         ai_usage_detection={"last_used": "45 days ago", "usage_frequency": "low"}),
+            Subscription(id=uid(), user_id=user.id, merchant="Planet Fitness",
+                         amount=24.99, billing_cycle="monthly", active=True,
+                         ai_usage_detection={"last_used": "1 week ago", "usage_frequency": "medium"}),
+            Subscription(id=uid(), user_id=user.id, merchant="iCloud Storage",
+                         amount=2.99, billing_cycle="monthly", active=True,
+                         ai_usage_detection={"last_used": "today", "usage_frequency": "daily"}),
+            Subscription(id=uid(), user_id=user.id, merchant="LinkedIn Premium",
+                         amount=39.99, billing_cycle="monthly", active=True,
+                         ai_usage_detection={"last_used": "60 days ago", "usage_frequency": "very_low"}),
+        ]
+        db.add_all(subscriptions)
+        monthly_sub_cost = sum(s.amount for s in subscriptions)
+        print(f"Created {len(subscriptions)} subscriptions (${monthly_sub_cost:.2f}/month)")
+
+        # ── Notifications ─────────────────────────────────────────────────────
+        notifications = [
+            Notification(id=uid(), user_id=user.id,
+                         title="🚨 Unusual Transaction Detected",
+                         message="A charge of $847.00 at 'Tech Store NYC' was flagged. "
+                                 "This is 3.2x your average transaction and occurred at 11:47 PM. "
+                                 "Please review and confirm.",
+                         type="alert", read_status=False,
+                         created_at=now - timedelta(hours=2)),
+            Notification(id=uid(), user_id=user.id,
+                         title="💡 AI Weekly Insight",
+                         message="Your savings rate this month is 38.4% — 18% above the national average. "
+                                 "At this pace, you'll reach your Emergency Fund goal in 3 months.",
+                         type="insight", read_status=False,
+                         created_at=now - timedelta(hours=6)),
+            Notification(id=uid(), user_id=user.id,
+                         title="⚠️ Budget Alert: Shopping",
+                         message="You've spent $847 in Shopping this month — 141% of your $600 budget. "
+                                 "Consider pausing non-essential purchases for the rest of the month.",
+                         type="warning", read_status=False,
+                         created_at=now - timedelta(hours=8)),
+            Notification(id=uid(), user_id=user.id,
+                         title="🎯 Goal Milestone Reached",
+                         message="Your Emergency Fund is now 78.9% funded ($14,200 of $18,000). "
+                                 "You're on track to complete it by August 2026.",
+                         type="insight", read_status=True,
+                         created_at=now - timedelta(days=1)),
+            Notification(id=uid(), user_id=user.id,
+                         title="📊 Monthly Report Ready",
+                         message="Your May 2026 financial report is ready. "
+                                 "Net savings: $1,847. Top category: Housing (38%). "
+                                 "Health score improved by 3 points to 82/100.",
+                         type="insight", read_status=True,
+                         created_at=now - timedelta(days=2)),
+            Notification(id=uid(), user_id=user.id,
+                         title="💰 Subscription Optimization",
+                         message="AI detected 2 underused subscriptions: Adobe CC ($54.99/mo, last used 45 days ago) "
+                                 "and LinkedIn Premium ($39.99/mo, last used 60 days ago). "
+                                 "Cancelling both saves $1,139.76/year.",
+                         type="warning", read_status=True,
+                         created_at=now - timedelta(days=3)),
+        ]
+        db.add_all(notifications)
+        print(f"Created {len(notifications)} notifications ({sum(1 for n in notifications if not n.read_status)} unread)")
+
+        db.commit()
+        print("\n" + "="*60)
+        print("DEMO ACCOUNT SEEDED SUCCESSFULLY")
+        print("="*60)
+        print(f"  Email:    {DEMO_EMAIL}")
+        print(f"  Password: {DEMO_PASSWORD}")
+        print(f"  Balance:  ${checking.balance + savings.balance + invest.balance:,.2f} total")
+        print(f"  Score:    82/100 (estimated)")
+        print(f"  Fraud:    1 pending alert")
+        print("="*60)
+
+    except Exception as e:
+        db.rollback()
+        print(f"SEED FAILED: {e}")
+        raise
+    finally:
+        db.close()
+
+if __name__ == "__main__":
+    seed()

backend/app/scripts/test_endpoints.py

@@ -0,0 +1,249 @@
+"""
+BankBot AI Endpoint Validation Script
+======================================
+Calls every AI endpoint and asserts the response shape is correct.
+
+Usage:
+    # From the backend/ directory with the server running:
+    python app/scripts/test_endpoints.py
+
+Exit codes:
+    0 — all tests passed
+    1 — one or more tests failed
+"""
+
+import sys
+import json
+import httpx
+
+BASE_URL = "http://127.0.0.1:8000"
+
+# ─── Result tracking ──────────────────────────────────────────────────────────
+
+results = []  # list of (name, passed, detail)
+
+def record(name: str, passed: bool, detail: str = ""):
+    results.append((name, passed, detail))
+
+# ─── Helpers ──────────────────────────────────────────────────────────────────
+
+def get(path: str, params: dict = None):
+    return httpx.get(f"{BASE_URL}{path}", params=params, timeout=60)
+
+def post(path: str, body: dict):
+    return httpx.post(f"{BASE_URL}{path}", json=body, timeout=60)
+
+def assert_keys(data: dict, *keys):
+    missing = [k for k in keys if k not in data]
+    if missing:
+        raise AssertionError(f"Missing keys: {missing}")
+
+# ─── Tests ────────────────────────────────────────────────────────────────────
+
+def test_health():
+    r = get("/health")
+    assert r.status_code == 200
+    assert r.json().get("status") == "healthy"
+    record("GET /health", True)
+
+def test_ai_status():
+    r = get("/api/ai/status")
+    assert r.status_code == 200
+    data = r.json()
+    assert_keys(data, "ai_backend", "ai_available", "db_type", "cache_type")
+    assert data["db_type"] in ("sqlite", "postgresql")
+    assert data["cache_type"] in ("redis", "memory")
+    record("GET /api/ai/status", True,
+           f"backend={data['ai_backend']} db={data['db_type']} cache={data['cache_type']}")
+
+def test_twin_predict():
+    r = get("/api/ai/twin/predict")
+    assert r.status_code == 200, f"HTTP {r.status_code}: {r.text}"
+    data = r.json()
+    assert_keys(data, "current_balance", "projected_balance", "percent_change",
+                "net_daily", "insight", "chart_data")
+    assert isinstance(data["chart_data"], list) and len(data["chart_data"]) >= 1
+    assert data["projected_balance"] >= 0.0, "projected_balance must be non-negative"
+    record("GET /api/ai/twin/predict", True,
+           f"balance=${data['current_balance']:,.2f} → ${data['projected_balance']:,.2f}")
+
+def test_twin_future():
+    r = get("/api/ai/twin/future", params={"months": 12})
+    assert r.status_code == 200, f"HTTP {r.status_code}: {r.text}"
+    data = r.json()
+    assert_keys(data, "savings_growth", "investment_growth", "debt_decline")
+    assert len(data["savings_growth"]) >= 1
+    assert len(data["investment_growth"]) >= 1
+    record("GET /api/ai/twin/future", True,
+           f"savings_points={len(data['savings_growth'])}")
+
+def test_twin_scenarios():
+    r = get("/api/ai/twin/scenarios", params={"months": 6})
+    assert r.status_code == 200, f"HTTP {r.status_code}: {r.text}"
+    data = r.json()
+    assert_keys(data, "status_quo", "frugal", "lifestyle_inflation")
+    for key in ("status_quo", "frugal", "lifestyle_inflation"):
+        assert "balance_projection" in data[key], f"Missing balance_projection in {key}"
+    record("GET /api/ai/twin/scenarios", True)
+
+def test_simulate_purchase():
+    r = post("/api/ai/simulate/purchase", {
+        "amount": 500.0, "merchant": "Test Store", "category": "Shopping"
+    })
+    assert r.status_code == 200, f"HTTP {r.status_code}: {r.text}"
+    data = r.json()
+    assert_keys(data, "risk_analysis", "projected_balance", "recommendation")
+    assert data["risk_analysis"]["risk_level"] in ("low", "medium", "high", "critical")
+    assert data["projected_balance"] >= 0.0
+    record("POST /api/ai/simulate/purchase", True,
+           f"risk={data['risk_analysis']['risk_level']}")
+
+def test_simulate_investment():
+    r = post("/api/ai/simulate/investment", {
+        "monthly_sip": 200.0, "asset_type": "stock", "lump_sum": 0.0
+    })
+    assert r.status_code == 200, f"HTTP {r.status_code}: {r.text}"
+    data = r.json()
+    assert_keys(data, "growth_projection", "is_affordable", "risk_analysis")
+    assert len(data["growth_projection"]) == 3, \
+        f"Expected 3 growth milestones (1/3/5 yr), got {len(data['growth_projection'])}"
+    record("POST /api/ai/simulate/investment", True,
+           f"affordable={data['is_affordable']}")
+
+def test_simulate_subscription():
+    # First fetch a real subscription ID from the optimize endpoint
+    r_subs = get("/api/ai/subscriptions/optimize")
+    assert r_subs.status_code == 200
+    subs = r_subs.json().get("subscriptions", [])
+    if not subs:
+        record("POST /api/ai/simulate/subscription", True, "skipped — no subscriptions in DB")
+        return
+    sub_id = subs[0]["id"]
+    r = post("/api/ai/simulate/subscription", {"subscription_ids": [sub_id]})
+    assert r.status_code == 200, f"HTTP {r.status_code}: {r.text}"
+    data = r.json()
+    assert_keys(data, "monthly_savings", "yearly_savings", "recommendation")
+    assert data["monthly_savings"] >= 0.0
+    record("POST /api/ai/simulate/subscription", True,
+           f"monthly_savings=${data['monthly_savings']:.2f}")
+
+def test_behavior_insights():
+    r = get("/api/ai/behavior/insights")
+    assert r.status_code == 200, f"HTTP {r.status_code}: {r.text}"
+    data = r.json()
+    assert_keys(data, "insights", "metrics")
+    assert isinstance(data["insights"], list) and len(data["insights"]) >= 1, \
+        "insights must be a non-empty list"
+    record("GET /api/ai/behavior/insights", True,
+           f"insights={len(data['insights'])}")
+
+def test_coaching_score():
+    r = get("/api/ai/coaching/score")
+    assert r.status_code == 200, f"HTTP {r.status_code}: {r.text}"
+    data = r.json()
+    assert_keys(data, "overall_score", "categories", "explanation", "actionable_improvements")
+    score = data["overall_score"]
+    assert 0 <= score <= 100, f"overall_score {score} out of [0, 100]"
+    expected_cats = ("savings_consistency", "debt_ratio", "spending_discipline",
+                     "emergency_funds", "investments", "subscription_management")
+    for cat in expected_cats:
+        assert cat in data["categories"], f"Missing category: {cat}"
+    assert len(data["actionable_improvements"]) >= 1
+    record("GET /api/ai/coaching/score", True, f"score={score}/100")
+
+def test_coaching_briefing():
+    # This endpoint calls an LLM — allow up to 120s for local Ollama inference
+    r = httpx.get(f"{BASE_URL}/api/ai/coaching/briefing", timeout=120)
+    assert r.status_code == 200, f"HTTP {r.status_code}: {r.text}"
+    data = r.json()
+    assert_keys(data, "date", "user_name", "briefing", "metrics")
+    assert isinstance(data["briefing"], str) and len(data["briefing"]) > 10
+    record("GET /api/ai/coaching/briefing", True,
+           f"briefing_len={len(data['briefing'])} chars")
+
+def test_subscriptions_optimize():
+    r = get("/api/ai/subscriptions/optimize")
+    assert r.status_code == 200, f"HTTP {r.status_code}: {r.text}"
+    data = r.json()
+    assert_keys(data, "subscriptions", "duplicates", "unused_subscriptions",
+                "yearly_savings_potential", "risk_analysis")
+    record("GET /api/ai/subscriptions/optimize", True,
+           f"subs={len(data['subscriptions'])} "
+           f"dupes={len(data['duplicates'])} "
+           f"unused={len(data['unused_subscriptions'])}")
+
+def test_fraud_analysis():
+    r = get("/api/ai/fraud/analysis")
+    assert r.status_code == 200, f"HTTP {r.status_code}: {r.text}"
+    data = r.json()
+    assert_keys(data, "total_alerts", "pending_reviews", "alerts")
+    assert isinstance(data["total_alerts"], int)
+    record("GET /api/ai/fraud/analysis", True,
+           f"alerts={data['total_alerts']}")
+
+def test_chat():
+    # This endpoint calls an LLM — allow up to 120s for local Ollama inference
+    r = httpx.post(f"{BASE_URL}/api/ai/chat",
+                   json={"message": "What is my current savings rate?"},
+                   timeout=120)
+    assert r.status_code == 200, f"HTTP {r.status_code}: {r.text}"
+    data = r.json()
+    assert "response" in data, "Missing 'response' key"
+    assert isinstance(data["response"], str) and len(data["response"]) > 5
+    record("POST /api/ai/chat", True,
+           f"response_len={len(data['response'])} chars")
+
+# ─── Runner ───────────────────────────────────────────────────────────────────
+
+TESTS = [
+    test_health,
+    test_ai_status,
+    test_twin_predict,
+    test_twin_future,
+    test_twin_scenarios,
+    test_simulate_purchase,
+    test_simulate_investment,
+    test_simulate_subscription,
+    test_behavior_insights,
+    test_coaching_score,
+    test_coaching_briefing,
+    test_subscriptions_optimize,
+    test_fraud_analysis,
+    test_chat,
+]
+
+if __name__ == "__main__":
+    print(f"\n{'─'*60}")
+    print(f"  BankBot AI Endpoint Validation  —  {BASE_URL}")
+    print(f"{'─'*60}\n")
+
+    for test_fn in TESTS:
+        name = test_fn.__name__.replace("test_", "").replace("_", " ")
+        try:
+            test_fn()
+            # result already recorded inside test_fn on success
+        except AssertionError as e:
+            record(name, False, str(e))
+        except Exception as e:
+            record(name, False, f"Exception: {e}")
+
+    # ── Summary table ─────────────────────────────────────────────────────────
+    print(f"\n{'─'*60}")
+    print(f"  {'TEST':<40} {'RESULT':<8} DETAIL")
+    print(f"{'─'*60}")
+
+    passed = 0
+    failed = 0
+    for test_name, ok, detail in results:
+        status = "✅ PASS" if ok else "❌ FAIL"
+        print(f"  {test_name:<40} {status:<8} {detail}")
+        if ok:
+            passed += 1
+        else:
+            failed += 1
+
+    print(f"{'─'*60}")
+    print(f"  {passed} passed  |  {failed} failed  |  {len(results)} total")
+    print(f"{'─'*60}\n")
+
+    sys.exit(0 if failed == 0 else 1)

backend/app/scripts/test_websocket.py

@@ -0,0 +1,159 @@
+"""
+BankBot WebSocket Streaming Validation Script
+==============================================
+Tests the /api/ai/chat/ws WebSocket endpoint for:
+  1. Streaming chat response (chat_start → chat_chunk(s) → chat_end)
+  2. Ping/pong keepalive
+  3. Invalid JSON error handling
+
+Usage:
+    # From the backend/ directory with the server running:
+    python app/scripts/test_websocket.py
+
+Exit codes:
+    0 — all tests passed
+    1 — one or more tests failed
+"""
+
+import sys
+import json
+import asyncio
+import websockets
+
+WS_URL = "ws://127.0.0.1:8000/api/ai/chat/ws"
+
+# ─── Result tracking ──────────────────────────────────────────────────────────
+
+results = []  # list of (name, passed, detail)
+
+def record(name: str, passed: bool, detail: str = ""):
+    results.append((name, passed, detail))
+
+# ─── Tests ────────────────────────────────────────────────────────────────────
+
+async def test_chat_streaming():
+    """
+    Sends a chat message and verifies the full streaming protocol:
+    chat_start → one or more chat_chunk → chat_end
+    """
+    async with websockets.connect(WS_URL, open_timeout=10) as ws:
+        await ws.send(json.dumps({
+            "type": "chat",
+            "message": "What is my current balance and savings rate?"
+        }))
+
+        got_start  = False
+        got_chunk  = False
+        got_end    = False
+        full_reply = ""
+
+        # Collect messages with a 30-second timeout
+        deadline = asyncio.get_event_loop().time() + 30
+        while asyncio.get_event_loop().time() < deadline:
+            try:
+                raw = await asyncio.wait_for(ws.recv(), timeout=30)
+            except asyncio.TimeoutError:
+                break
+
+            msg = json.loads(raw)
+            t   = msg.get("type")
+
+            if t == "chat_start":
+                got_start = True
+            elif t == "chat_chunk":
+                got_chunk = True
+                full_reply += msg.get("content", "")
+            elif t == "chat_end":
+                got_end = True
+                break
+            elif t == "error":
+                raise AssertionError(f"Server returned error: {msg.get('message')}")
+
+        assert got_start,  "Never received chat_start"
+        assert got_chunk,  "Never received any chat_chunk"
+        assert got_end,    "Never received chat_end"
+        assert len(full_reply) > 5, f"Assembled reply is too short: '{full_reply}'"
+
+        record("WS chat streaming", True,
+               f"reply_len={len(full_reply)} chars | preview: {full_reply[:80].strip()}...")
+
+
+async def test_ping_pong():
+    """
+    Sends a ping and verifies the server responds with pong.
+    """
+    async with websockets.connect(WS_URL, open_timeout=10) as ws:
+        await ws.send(json.dumps({"type": "ping"}))
+
+        raw = await asyncio.wait_for(ws.recv(), timeout=10)
+        msg = json.loads(raw)
+
+        assert msg.get("type") == "pong", \
+            f"Expected pong, got: {msg}"
+
+        record("WS ping/pong", True)
+
+
+async def test_invalid_json():
+    """
+    Sends a non-JSON string and verifies the server returns an error message.
+    """
+    async with websockets.connect(WS_URL, open_timeout=10) as ws:
+        await ws.send("this is not valid json {{{{")
+
+        raw = await asyncio.wait_for(ws.recv(), timeout=10)
+        msg = json.loads(raw)
+
+        assert msg.get("type") == "error", \
+            f"Expected error response, got: {msg}"
+
+        record("WS invalid JSON handling", True,
+               f"error_msg={msg.get('message', '')[:60]}")
+
+
+# ─── Runner ───────────────────────────────────────────────────────────────────
+
+async def main():
+    print(f"\n{'─'*60}")
+    print(f"  BankBot WebSocket Validation  —  {WS_URL}")
+    print(f"{'─'*60}\n")
+
+    tests = [
+        ("WS chat streaming",       test_chat_streaming),
+        ("WS ping/pong",            test_ping_pong),
+        ("WS invalid JSON handling", test_invalid_json),
+    ]
+
+    for name, test_fn in tests:
+        try:
+            await test_fn()
+        except AssertionError as e:
+            record(name, False, str(e))
+        except Exception as e:
+            record(name, False, f"Exception: {type(e).__name__}: {e}")
+
+    # ── Summary table ─────────────────────────────────────────────────────────
+    print(f"\n{'─'*60}")
+    print(f"  {'TEST':<35} {'RESULT':<8} DETAIL")
+    print(f"{'─'*60}")
+
+    passed = 0
+    failed = 0
+    for test_name, ok, detail in results:
+        status = "✅ PASS" if ok else "❌ FAIL"
+        print(f"  {test_name:<35} {status:<8} {detail}")
+        if ok:
+            passed += 1
+        else:
+            failed += 1
+
+    print(f"{'─'*60}")
+    print(f"  {passed} passed  |  {failed} failed  |  {len(results)} total")
+    print(f"{'─'*60}\n")
+
+    return failed
+
+
+if __name__ == "__main__":
+    failed_count = asyncio.run(main())
+    sys.exit(0 if failed_count == 0 else 1)

backend/app/transactions/router.py

@@ -0,0 +1,60 @@
+"""
+Transactions router — paginated transaction history with filtering.
+"""
+from typing import Optional
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy.orm import Session
+from sqlalchemy import desc
+
+from app.database.database import get_db
+from app.database.models import User, Account, Transaction
+
+router = APIRouter(prefix="/api/transactions", tags=["Transactions"])
+
+def _resolve_user(db: Session, user_id: Optional[str]) -> str:
+    if user_id:
+        return user_id
+    user = db.query(User).first()
+    if not user:
+        from fastapi import HTTPException
+        raise HTTPException(status_code=404, detail="No users found.")
+    return user.id
+
+@router.get("/")
+def get_transactions(
+    user_id: Optional[str] = None,
+    page: int = Query(default=1, ge=1),
+    limit: int = Query(default=20, ge=1, le=100),
+    category: Optional[str] = None,
+    type: Optional[str] = None,
+    db: Session = Depends(get_db),
+):
+    uid = _resolve_user(db, user_id)
+    account_ids = [a.id for a in db.query(Account).filter(Account.user_id == uid).all()]
+
+    query = db.query(Transaction).filter(Transaction.account_id.in_(account_ids))
+    if category:
+        query = query.filter(Transaction.category == category)
+    if type:
+        query = query.filter(Transaction.type == type)
+
+    total = query.count()
+    transactions = query.order_by(desc(Transaction.timestamp)).offset((page - 1) * limit).limit(limit).all()
+
+    return {
+        "transactions": [
+            {
+                "id": t.id,
+                "merchant": t.merchant or "Unknown",
+                "category": t.category or "Other",
+                "amount": t.amount if t.type == "credit" else -abs(t.amount),
+                "type": t.type,
+                "timestamp": t.timestamp.isoformat() if t.timestamp else None,
+                "tags": t.tags or [],
+            }
+            for t in transactions
+        ],
+        "total": total,
+        "page": page,
+        "pages": (total + limit - 1) // limit,
+    }

backend/app/websocket/connection_manager.py

@@ -0,0 +1,41 @@
+from typing import Dict, List
+from fastapi import WebSocket
+
+class WebSocketConnectionManager:
+    def __init__(self):
+        # Maps user_id -> List[WebSocket]
+        self.active_connections: Dict[str, List[WebSocket]] = {}
+
+    async def connect(self, websocket: WebSocket, user_id: str):
+        await websocket.accept()
+        if user_id not in self.active_connections:
+            self.active_connections[user_id] = []
+        self.active_connections[user_id].append(websocket)
+        print(f"WebSocket client connected for user: {user_id}")
+
+    def disconnect(self, websocket: WebSocket, user_id: str):
+        if user_id in self.active_connections:
+            if websocket in self.active_connections[user_id]:
+                self.active_connections[user_id].remove(websocket)
+            if not self.active_connections[user_id]:
+                del self.active_connections[user_id]
+        print(f"WebSocket client disconnected for user: {user_id}")
+
+    async def send_personal_message(self, message: dict, user_id: str):
+        if user_id in self.active_connections:
+            for connection in self.active_connections[user_id]:
+                try:
+                    await connection.send_json(message)
+                except Exception as e:
+                    print(f"Error sending message to {user_id}: {e}")
+
+    async def broadcast(self, message: dict):
+        for user_id, connections in self.active_connections.items():
+            for connection in connections:
+                try:
+                    await connection.send_json(message)
+                except Exception as e:
+                    print(f"Error broadcasting message: {e}")
+
+# Global Connection Manager instance
+ws_manager = WebSocketConnectionManager()

backend/app/websocket/router.py

@@ -0,0 +1,142 @@
+"""
+WebSocket chat router — real-time streaming AI chat with:
+- Prompt injection prevention
+- Input sanitization
+- Heartbeat/ping support
+- Structured error responses
+- Observability metrics tracking
+"""
+import json
+import re
+from fastapi import APIRouter, WebSocket, WebSocketDisconnect, Query
+from app.database.database import SessionLocal
+from app.database.models import User
+from app.websocket.connection_manager import ws_manager
+from app.ai.chat import stream_chat_response
+from app.middleware.logging import ws_logger, metrics
+
+router = APIRouter(tags=["WebSockets"])
+
+# ─── Prompt injection patterns ────────────────────────────────────────────────
+_INJECTION_PATTERNS = [
+    r"ignore\s+(all\s+)?previous\s+instructions",
+    r"you\s+are\s+now\s+a",
+    r"forget\s+(everything|all)",
+    r"new\s+system\s+prompt",
+    r"disregard\s+(your|all)",
+    r"act\s+as\s+(if\s+you\s+are|a\s+different)",
+    r"jailbreak",
+    r"dan\s+mode",
+    r"developer\s+mode",
+    r"<\s*script",
+    r"javascript:",
+]
+_INJECTION_RE = re.compile("|".join(_INJECTION_PATTERNS), re.IGNORECASE)
+
+MAX_MESSAGE_LENGTH = 2000
+
+def sanitize_prompt(text: str) -> tuple[str, bool]:
+    """
+    Returns (sanitized_text, is_safe).
+    Strips control characters, checks for injection patterns.
+    """
+    # Strip null bytes and control characters (keep newlines/tabs)
+    cleaned = re.sub(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]", "", text)
+    # Truncate
+    cleaned = cleaned[:MAX_MESSAGE_LENGTH]
+    # Check for injection
+    if _INJECTION_RE.search(cleaned):
+        return cleaned, False
+    return cleaned, True
+
+
+@router.websocket("/api/ai/chat/ws")
+async def websocket_chat_endpoint(
+    websocket: WebSocket,
+    user_id: str = Query(None),
+):
+    db = SessionLocal()
+
+    # Resolve user
+    if not user_id:
+        user = db.query(User).first()
+        if user:
+            user_id = user.id
+        else:
+            await websocket.accept()
+            await websocket.send_json({
+                "type": "error",
+                "message": "No users found. Run: python app/scripts/seed_demo.py"
+            })
+            await websocket.close()
+            db.close()
+            return
+
+    await ws_manager.connect(websocket, user_id)
+    metrics.ws_connects += 1
+    ws_logger.info("WebSocket connected", extra={"user_id": user_id[:8]})
+
+    try:
+        while True:
+            data = await websocket.receive_text()
+
+            try:
+                payload = json.loads(data)
+            except json.JSONDecodeError:
+                await websocket.send_json({"type": "error", "message": "Invalid JSON"})
+                continue
+
+            msg_type = payload.get("type", "chat")
+
+            # ── Heartbeat ────────────────────────────────────────────────────
+            if msg_type == "ping":
+                await websocket.send_json({"type": "pong"})
+                continue
+
+            # ── Chat message ─────────────────────────────────────────────────
+            if msg_type == "chat":
+                raw_prompt = payload.get("message", "").strip()
+
+                if not raw_prompt:
+                    await websocket.send_json({"type": "error", "message": "Message cannot be empty"})
+                    continue
+
+                # Sanitize + injection check
+                prompt, is_safe = sanitize_prompt(raw_prompt)
+                if not is_safe:
+                    ws_logger.warning("Prompt injection attempt blocked", extra={"user_id": user_id[:8]})
+                    await websocket.send_json({
+                        "type": "error",
+                        "message": "I can only help with financial questions about your accounts."
+                    })
+                    continue
+
+                await websocket.send_json({"type": "chat_start"})
+
+                try:
+                    for chunk in stream_chat_response(db, user_id, prompt):
+                        if chunk:
+                            await websocket.send_json({"type": "chat_chunk", "content": chunk})
+                except Exception as e:
+                    ws_logger.error("AI streaming error", extra={"error": str(e)[:100]})
+                    await websocket.send_json({
+                        "type": "error",
+                        "message": "AI response failed. Please try again."
+                    })
+
+                await websocket.send_json({"type": "chat_end"})
+
+            else:
+                await websocket.send_json({
+                    "type": "error",
+                    "message": f"Unknown message type: {msg_type}"
+                })
+
+    except WebSocketDisconnect:
+        ws_manager.disconnect(websocket, user_id)
+        ws_logger.info("WebSocket disconnected", extra={"user_id": user_id[:8]})
+    except Exception as e:
+        ws_logger.error("WebSocket error", extra={"user_id": user_id[:8], "error": str(e)[:100]})
+        ws_manager.disconnect(websocket, user_id)
+    finally:
+        db.close()