Deploy to HF Spaces

.env.example

@@ -0,0 +1,51 @@
+# ============================================================================
+# LLM Provider Configuration
+# ============================================================================
+# Choose your provider: openai, anthropic, google, huggingface
+LLM_PROVIDER=openai
+
+# Set the API key for your chosen provider (only one needed)
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+GOOGLE_API_KEY=AI...
+HF_TOKEN=hf_...
+
+# Optional: override the default model for your provider
+# MODEL_NAME=gpt-4o
+# MODEL_MAX_TOKENS=512
+
+# HuggingFace-specific: inference provider (together, sambanova, etc.)
+# HF_INFERENCE_PROVIDER=together
+
+
+# ============================================================================
+# Database Configuration (PostgreSQL)
+# ============================================================================
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=cashy_demo
+DB_USER=financial_advisor
+DB_PASSWORD=
+
+
+# ============================================================================
+# LangSmith Configuration (optional — for tracing and evaluation)
+# ============================================================================
+LANGSMITH_TRACING=true
+LANGSMITH_API_KEY=
+LANGSMITH_PROJECT=cashy-financial-advisor
+LANGSMITH_ENDPOINT=https://api.smith.langchain.com
+
+
+# ============================================================================
+# Application Settings
+# ============================================================================
+# App mode: "demo" (seeded showcase data) or "personal" (your real financial data)
+APP_MODE=personal
+
+# Override database names per mode (optional — defaults shown below)
+# DB_NAME_DEMO=cashy_demo
+# DB_NAME_PERSONAL=financial_db
+
+ENVIRONMENT=development
+DEBUG=true

.github/workflows/deploy-hf.yml

@@ -0,0 +1,25 @@
+name: Deploy to HuggingFace Space
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Prepare and push to HuggingFace Space
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          git config user.email "actions@github.com"
+          git config user.name "GitHub Actions"
+          cat .hf/metadata.yml README.md > README.tmp && mv README.tmp README.md
+          rm -rf docs/*.gif docs/*.mp4
+          git checkout --orphan hf-deploy
+          git add -A
+          git commit -m "Deploy to HF Spaces"
+          git push --force https://SeasonalFall84:$HF_TOKEN@huggingface.co/spaces/SeasonalFall84/cashy hf-deploy:main

.gitignore

@@ -0,0 +1,97 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual Environments
+venv/
+env/
+ENV/
+env.bak/
+venv.bak/
+.venv/
+
+# PyCharm
+.idea/
+
+# VS Code
+.vscode/
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# LangSmith / LangChain
+.langsmith/
+langsmith_cache/
+
+# PostgreSQL
+*.sql.backup
+*.dump
+
+# Logs
+*.log
+logs/
+*.log.*
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Reflection reports (optional - uncomment if you don't want to track these)
+# reflection_report_*.md
+
+# Temporary files
+*.tmp
+*.temp
+.cache/
+
+# Claude Code project files
+.claude/
+
+# Developer documentation (internal use only)
+dev/
+
+# Old Langflow agent exports (kept locally for reference)
+agent_versions/
+
+# Eval cases (local only)
+eval_cases/
+
+# VBA macros (local only)
+macros/

.hf/metadata.yml

@@ -0,0 +1,12 @@
+---
+title: Cashy - AI Financial Advisor
+emoji: "\U0001F4B0"
+colorFrom: indigo
+colorTo: blue
+sdk: gradio
+sdk_version: "6.5.1"
+app_file: app.py
+pinned: false
+license: mit
+short_description: AI-powered personal finance advisor with BYOK LLM support
+---

CLAUDE.md

@@ -0,0 +1,114 @@
+# Claude Code Instructions for Cashy Project
+
+## Project Summary
+
+Cashy is an AI-powered personal financial advisor built with LangGraph + LangChain + Gradio + PostgreSQL. It queries a financial database to answer questions about accounts, transactions, and spending. Supports multiple LLM providers (OpenAI, Anthropic, Google, HuggingFace) plus a free tier for zero-config demo access.
+
+**Tech Stack**: LangGraph (orchestration) + LangChain (tools + LLM abstractions) + Gradio (UI) + PostgreSQL (data + checkpoints) + LangSmith (tracing)
+
+## How to Run
+
+```bash
+# Configure your LLM provider in .env (see .env.example)
+# Personal mode (default — connects to financial_db):
+uv run python app.py
+
+# Demo mode (seeded showcase data in cashy_demo):
+APP_MODE=demo uv run python app.py
+```
+
+## Project Structure
+
+```
+cashy-poc/
+├── app.py                    # Entry point (logging, checkpointer, Gradio)
+├── pyproject.toml            # Dependencies (managed by uv)
+├── .env.example              # Template for environment variables
+├── src/
+│   ├── config.py             # Pydantic BaseSettings — app mode, multi-provider config
+│   ├── ui.py                 # Gradio Blocks UI (chat, sidebar, thread history, themes)
+│   ├── agent/
+│   │   ├── graph.py          # LangGraph StateGraph factory
+│   │   ├── nodes.py          # LLM factory (5 providers incl. free-tier), call_model, should_continue
+│   │   ├── prompts.py        # System prompts (demo + personal modes)
+│   │   └── state.py          # AgentState (extends MessagesState)
+│   ├── tools/
+│   │   ├── __init__.py       # Exports all_tools list
+│   │   ├── finance_query.py  # @tool — custom SELECT queries
+│   │   ├── account_balance.py
+│   │   ├── recent_transactions.py
+│   │   ├── spending_by_category.py
+│   │   ├── all_accounts.py
+│   │   ├── create_transaction.py
+│   │   └── generate_chart.py # @tool — matplotlib charts (bar, pie, line, grouped)
+│   └── db/
+│       └── connection.py     # psycopg2 context manager
+├── eval_cases/               # Evaluation test cases (JSON)
+├── scripts/
+│   ├── run_eval.py           # Eval runner
+│   ├── seed_demo_db.sql      # Demo DB schema + seed data
+│   └── sanitize_agent_export.py
+├── dev/                      # Developer documentation
+│   ├── active/               # In-progress task docs
+│   └── archive/              # Completed task docs
+└── .env                      # Credentials (not committed)
+```
+
+## Key Technical Details
+
+- **Package manager**: uv (not pip). Use `uv sync` and `uv run`.
+- **LLM providers**: OpenAI, Anthropic, Google, HuggingFace, **free-tier** — configured via `LLM_PROVIDER` env var or auto-detected from API keys (priority: openai > anthropic > google > huggingface). Free-tier is auto-detected in demo mode when `HF_TOKEN` is the only key set.
+- **Free-tier provider**: Uses the Space owner's `HF_TOKEN` (captured at startup as `_SPACE_HF_TOKEN` in nodes.py). Locked to `Qwen/Qwen2.5-7B-Instruct` — no model override, no inference provider param (HF auto-routes). UI hides API key input, Save button, and model textbox when selected. Responses include a disclaimer nudging users toward paid providers.
+- **Default models**: gpt-5-mini, claude-sonnet-4-20250514, gemini-2.5-flash, Llama-3.3-70B-Instruct, Qwen2.5-7B-Instruct (free-tier). Users can override via the model name textbox in the sidebar (except free-tier).
+- **HF inference providers**: When HuggingFace is selected, a dropdown lets users pick from 14 inference providers (cerebras, groq, together, etc.).
+- **Lazy imports**: Provider packages are imported inside if-branches in `nodes.py` to avoid errors when only one provider is installed.
+- **ChatHuggingFace** does NOT support `with_structured_output()` — use `bind_tools()`.
+- **Latin-1 sanitization**: HuggingFace's HTTP transport uses latin-1 encoding. `_sanitize_for_latin1()` in nodes.py strips non-latin-1 chars from messages and tool descriptions before sending to HF. Applies to both `huggingface` and `free-tier` providers.
+- **Prompt guidelines**: System prompts include "NEVER show SQL queries in responses" and "Always execute tools immediately" — critical for smaller models (7B) that otherwise dump raw SQL.
+- **Memory**: LangGraph MessagesState (session) + PostgresSaver (cross-session via psycopg v3).
+- **Tools use psycopg2**, checkpointer uses psycopg v3 — both coexist in pyproject.toml.
+- **System prompt**: Has `{today}` and `{year}` placeholders injected dynamically in `call_model()`.
+- **9 tools**: finance_db_query, get_account_balance, get_recent_transactions, get_spending_by_category, get_all_accounts, create_transaction, update_transaction, delete_transaction, generate_chart.
+- **Human-in-the-loop**: Write tools (create/update/delete) use LangGraph `interrupt()` for user confirmation before DB writes. UI handles via `pending_interrupt` state + `Command(resume=...)`.
+- **Chart rendering**: `generate_chart` saves matplotlib PNGs to /tmp. UI scans ToolMessages for `chart_path` and renders inline via Gradio's `{"path": ...}` format.
+- **Session memory**: `gr.State` holds a per-session `thread_id` so follow-up messages share LangGraph conversation context.
+- **Thread management**: "New Chat" button + "Chat History" accordion to start fresh or resume past threads.
+- **Transfers**: `get_recent_transactions` collapses transfer entries into single rows with `from_account`/`to_account`.
+- **App mode**: `APP_MODE=demo` (cashy_demo DB, Glass indigo theme, freelancer prompt) or `APP_MODE=personal` (financial_db, Default theme, generic prompt). Default: personal.
+- **Themes**: Demo uses `gr.themes.Glass(primary_hue="indigo")`, personal uses `gr.themes.Default()`.
+
+## Database
+
+- **Host**: localhost:5432, **User**: financial_advisor
+- **Demo DB**: `cashy_demo` — English, US freelancer, USD. Seed: `scripts/seed_demo_db.sql`
+- **Personal DB**: `financial_db` — user's real financial data, same schema
+- **Schema**: 11 tables + 8 views (see `dev/DATABASE_SCHEMA.md`)
+- Key tables: accounts, transactions, transaction_entries, categories, budgets
+- Key views: v_transaction_details, v_monthly_spending, v_account_summary
+
+## Development Guidelines
+
+- Prefer editing existing files over creating new ones
+- Run code to validate — `uv run python app.py` or Python REPL
+- Keep `dev/active/` task docs updated for complex work
+- Never commit `.env` or files with credentials
+- Use structured logging (`cashy.agent`, `cashy.tools`, `cashy.db`, `cashy.ui`)
+
+## Rules
+
+- **Python:** Always run with `uv run python`, never `python` or `python3` directly
+- **Libraries:** Use Context7 MCP (`resolve-library-id` → `query-docs`) for external docs
+- **Git commits:** Single-line commit message. Never include Co-Authored-By
+- **Language:** English only (portfolio project targeting US/international clients)
+- **Timezone:** Assume `America/Mexico_City` unless specified
+- **Secrets:** NEVER hardcode API keys, tokens, passwords, or secrets in commands, code, or chat output. Always reference them via environment variables from `.env` files (e.g., `$API_KEY`). If a needed var isn't set, ask the user to add it to `.env` — never ask for the raw value
+
+## Quick References
+
+- **Live Demo**: https://huggingface.co/spaces/SeasonalFall84/cashy (deployed from `main`, demo mode)
+- **Architecture**: `dev/ARCHITECTURE.md`
+- **DB Schema**: `dev/DATABASE_SCHEMA.md`
+- **Branches**: `dev/BRANCHES.md`
+- **Troubleshooting**: `dev/TROUBLESHOOTING.md`
+- **Eval cases**: `eval_cases/eval_cases_v1.json`
+- **Env template**: `.env.example`

README.md

@@ -0,0 +1,183 @@
+---
+title: Cashy - AI Financial Advisor
+emoji: "\U0001F4B0"
+colorFrom: indigo
+colorTo: blue
+sdk: gradio
+sdk_version: "6.5.1"
+app_file: app.py
+pinned: false
+license: mit
+short_description: AI-powered personal finance advisor with BYOK LLM support
+---
+# Cashy - AI Financial Advisor
+
+An AI-powered personal finance agent that answers natural language questions about accounts, transactions, spending, and budgets by querying a real PostgreSQL database. Built with LangGraph, LangChain, and your choice of LLM provider.
+
+**[Try the live demo](https://huggingface.co/spaces/SeasonalFall84/cashy)** - no API key required (free tier included)
+
+**[See the YT demo video](https://youtu.be/Ln5vl8dd5aI)**
+
+![Cashy Demo](docs/demo.gif)
+
+## The Problem
+
+Freelancers juggle multiple bank accounts, payment platforms, credit cards, and investment accounts. Tracking spending, comparing budgets, and answering simple financial questions means logging into several dashboards and doing mental math.
+
+## The Solution
+
+Cashy is a conversational AI agent that sits on top of your financial database. Ask a question in plain English - Cashy picks the right tool, queries the database, and gives you an accurate answer with real numbers.
+
+## Features
+
+- **Multi-provider LLM** - OpenAI, Anthropic, Google, HuggingFace, or free tier (auto-detected from API key)
+- **BYOK (Bring Your Own Key)** - Paste your API key in the sidebar, switch providers on the fly
+- **Free tier** - Zero-friction demo with Qwen 2.5 7B, no API key needed
+- **9 specialized tools** - Account balances, transactions, spending analysis, budget tracking, CRUD operations, custom SQL, and chart generation
+- **Human-in-the-loop** - Write operations (create/update/delete) require user confirmation before executing
+- **Chart generation** - Bar, pie, line, and grouped comparison charts rendered inline via matplotlib
+- **Persistent memory** - Conversation history stored in PostgreSQL via LangGraph checkpoints
+- **Demo / Personal mode** - Switch between showcase data and your real finances via `APP_MODE`
+- **Demo data included** - 11 accounts, 180+ transactions, 23 budgets for a US freelancer scenario
+
+## Quick Setup
+
+```bash
+# 1. Clone and install
+git clone https://github.com/MarioAderman/cashy-poc.git
+cd cashy-poc
+uv sync
+
+# 2. Configure your LLM provider
+cp .env.example .env
+# Edit .env - paste your API key (OpenAI, Anthropic, Google, or HuggingFace)
+
+# 3. Seed the demo database
+createdb -U postgres cashy_demo
+psql -U postgres -d cashy_demo -f scripts/seed_demo_db.sql
+
+# 4. Run (demo mode with showcase data)
+APP_MODE=demo uv run python app.py
+
+# Or run with your own database (default)
+uv run python app.py
+```
+
+Open http://localhost:7860 - Cashy greets you with a welcome message and a reference card.
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────┐
+│              Gradio UI (port 7860)                    │
+│    Chat + BYOK sidebar + provider switcher           │
+└──────────────────────┬───────────────────────────────┘
+                       │
+┌──────────────────────▼───────────────────────────────┐
+│            LangGraph Agent (StateGraph)               │
+│  START → agent → should_continue → tools → agent → END│
+│                       │                               │
+│  ┌────────────────────┼────────────────────────┐     │
+│  │  LLM (configurable)│ ToolNode (9 tools)     │     │
+│  │  OpenAI / Anthropic │ via LangChain @tool    │     │
+│  │  Google / HuggingFace│ + interrupt() for     │     │
+│  │  Free tier (Qwen)  │   write operations      │     │
+│  └────────────────────┴────────────────────────┘     │
+└──────────────────────┬───────────────────────────────┘
+                       │
+        ┌──────────────┼──────────────┐
+        ▼              ▼              ▼
+┌──────────────┐ ┌──────────┐ ┌─────────────┐
+│ PostgreSQL   │ │LangSmith │ │ PostgreSQL   │
+│ (financial   │ │(tracing) │ │ (checkpoints)│
+│  data)       │ │          │ │              │
+└──────────────┘ └──────────┘ └────────────��┘
+```
+
+## Tech Stack
+
+| Component | Technology |
+|---|---|
+| Agent orchestration | LangGraph + LangChain |
+| LLM | OpenAI, Anthropic, Google, HuggingFace, Free tier (configurable) |
+| UI | Gradio Blocks (chat + BYOK sidebar) |
+| Database | PostgreSQL (financial data + conversation checkpoints) |
+| Tracing | LangSmith |
+| Package manager | uv |
+| Config | Pydantic Settings + .env (auto-detects provider from API key) |
+
+## Configuration
+
+Copy `.env.example` and set your preferred provider's API key. Cashy auto-detects which provider to use, or you can set `LLM_PROVIDER` explicitly.
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `APP_MODE` | `demo` or `personal` | `personal` |
+| `LLM_PROVIDER` | Force a provider (optional) | Auto-detected from API key |
+| `OPENAI_API_KEY` | OpenAI API key | - |
+| `ANTHROPIC_API_KEY` | Anthropic API key | - |
+| `GOOGLE_API_KEY` | Google AI API key | - |
+| `HF_TOKEN` | HuggingFace token | - |
+| `MODEL_NAME` | Override default model | Per-provider default |
+| `DB_NAME_DEMO` | Demo database name | `cashy_demo` |
+| `DB_NAME_PERSONAL` | Personal database name | `financial_db` |
+| `LANGSMITH_API_KEY` | LangSmith tracing (optional) | - |
+
+**Default models:** gpt-5-mini, claude-sonnet-4-20250514, gemini-2.5-flash, Llama-3.3-70B-Instruct, Qwen2.5-7B-Instruct (free tier)
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `finance_db_query` | Execute custom SELECT queries |
+| `get_account_balance` | Get balance for a specific account |
+| `get_recent_transactions` | Fetch recent transaction history |
+| `get_spending_by_category` | Monthly spending by category |
+| `get_all_accounts` | List all accounts with balances |
+| `create_transaction` | Record new income/expense/transfer |
+| `update_transaction` | Modify existing transactions |
+| `delete_transaction` | Remove transactions |
+| `generate_chart` | Bar, pie, line, grouped bar charts from SQL results |
+
+## Project Structure
+
+```
+cashy-poc/
+├── app.py                    # Entry point
+├── pyproject.toml            # Dependencies (managed by uv)
+├── .env.example              # Environment variable template
+├── src/
+│   ├── config.py             # Multi-provider config, app mode, auto-detection
+│   ├── ui.py                 # Gradio Blocks UI (chat, sidebar, BYOK, themes)
+│   ├── agent/
+│   │   ├── graph.py          # LangGraph StateGraph factory
+│   │   ├── nodes.py          # LLM factory (5 providers), call_model, routing
+│   │   ├── prompts.py        # System prompts (demo + personal modes)
+│   │   └── state.py          # AgentState (extends MessagesState)
+│   ├── tools/
+│   │   ├── finance_query.py  # Custom SQL SELECT queries
+│   │   ├── account_balance.py
+│   │   ├── recent_transactions.py
+│   │   ├── spending_by_category.py
+│   │   ├── all_accounts.py
+│   │   ├── create_transaction.py
+│   │   ├── update_transaction.py
+│   │   ├── delete_transaction.py
+│   │   └── generate_chart.py # matplotlib chart generation
+│   └── db/
+│       └── connection.py     # psycopg2 context manager
+└── scripts/
+    ├── run_eval.py           # Eval runner
+    └── seed_demo_db.sql      # Demo database schema + seed data
+```
+
+## Prerequisites
+
+- Python 3.10+
+- PostgreSQL running locally
+- [uv](https://docs.astral.sh/uv/) package manager
+- At least one LLM API key (or use the free tier in demo mode)
+
+## License
+
+MIT

app.py

@@ -0,0 +1,44 @@
+import logging
+from src.config import settings
+from src.agent.graph import create_agent
+from src.ui import create_ui
+from langgraph.checkpoint.postgres import PostgresSaver
+
+logging.basicConfig(
+    level=logging.DEBUG if settings.debug else logging.INFO,
+    format="%(asctime)s [%(name)-12s] %(levelname)-7s %(message)s",
+    datefmt="%H:%M:%S",
+)
+# Quiet noisy third-party loggers
+for name in ("httpx", "httpcore", "urllib3", "hf_transfer", "gradio", "uvicorn",
+              "openai", "anthropic", "google", "google.auth", "google.generativeai",
+              "matplotlib", "psycopg", "psycopg.pool"):
+    logging.getLogger(name).setLevel(logging.WARNING)
+
+logger = logging.getLogger("cashy.main")
+
+
+def main():
+    provider = settings.resolved_provider
+    model_name = settings.model_name or "default"
+    logger.info("Mode:     %s", settings.app_mode)
+    if provider:
+        logger.info("LLM:      %s (%s)", provider, model_name)
+    else:
+        logger.warning("LLM:      No API key configured — user must provide one via UI")
+    logger.info("Database: %s@%s:%s", settings.resolved_db_name, settings.db_host[:8] + "...", settings.db_port)
+
+    with PostgresSaver.from_conn_string(settings.database_url) as checkpointer:
+        checkpointer.setup()
+        logger.info("Checkpoint tables ready")
+
+        agent = create_agent(checkpointer=checkpointer)
+        logger.info("Agent graph compiled")
+
+        demo, theme = create_ui(agent)
+        logger.info("Launching Gradio on http://localhost:7860")
+        demo.launch(server_name="0.0.0.0", server_port=7860, theme=theme)
+
+
+if __name__ == "__main__":
+    main()

llms.txt

@@ -0,0 +1,76 @@
+# Cashy - AI Financial Advisor
+
+> AI-powered personal finance agent that queries a PostgreSQL database to answer natural language questions about accounts, transactions, spending, and budgets.
+
+## Stack
+
+- LangGraph (agent orchestration, StateGraph)
+- LangChain (tool abstractions, LLM bindings)
+- Gradio (web UI)
+- PostgreSQL (financial data + conversation checkpoints)
+- LangSmith (tracing)
+- matplotlib (chart generation)
+
+## LLM Providers
+
+Supports OpenAI, Anthropic, Google, HuggingFace, and a free tier (Qwen 2.5 7B). Auto-detected from API key or set via LLM_PROVIDER env var. BYOK input in sidebar.
+
+## Agent Architecture
+
+LangGraph StateGraph: START -> call_model -> should_continue -> [tools | END]
+- call_model: injects system prompt + invokes LLM with bound tools
+- should_continue: routes to ToolNode if tool calls present, else END
+- Memory: MessagesState (session) + PostgresSaver (cross-session)
+
+## Tools (9)
+
+- finance_db_query: execute custom SELECT queries
+- get_account_balance: balance for a specific account
+- get_recent_transactions: recent transaction history
+- get_spending_by_category: monthly spending breakdown
+- get_all_accounts: list all accounts with balances
+- create_transaction: record new income/expense/transfer (requires confirmation)
+- update_transaction: modify existing transactions (requires confirmation)
+- delete_transaction: remove transactions (requires confirmation)
+- generate_chart: bar, pie, line, grouped bar charts via matplotlib
+
+Write tools use LangGraph interrupt() for human-in-the-loop confirmation.
+
+## Key Files
+
+- app.py: entry point (logging, checkpointer setup, Gradio launch)
+- src/config.py: Pydantic BaseSettings, multi-provider config, auto-detection
+- src/ui.py: Gradio Blocks UI (chat, BYOK sidebar, provider switcher, themes)
+- src/agent/graph.py: LangGraph StateGraph factory
+- src/agent/nodes.py: LLM factory (5 providers), call_model, should_continue
+- src/agent/prompts.py: system prompts for demo and personal modes
+- src/agent/state.py: AgentState (extends MessagesState)
+- src/tools/__init__.py: exports all_tools list
+- src/db/connection.py: psycopg2 context manager
+- scripts/seed_demo_db.sql: demo database schema + seed data
+
+## Modes
+
+- demo: cashy_demo DB, Glass indigo theme, US freelancer persona, free tier available
+- personal: financial_db, Default theme, generic financial advisor persona
+
+## Database Schema
+
+Key tables: accounts, transactions, transaction_entries, categories, budgets
+Key views: v_transaction_details, v_monthly_spending, v_account_summary
+11 tables + 8 views total. Demo DB: 11 accounts, 180+ transactions, 23 budgets (USD).
+
+## Running
+
+Requires Python 3.10+, PostgreSQL, uv package manager.
+
+```
+uv sync
+cp .env.example .env  # add your API key
+APP_MODE=demo uv run python app.py  # demo mode
+uv run python app.py                # personal mode
+```
+
+## Live Demo
+
+https://huggingface.co/spaces/SeasonalFall84/cashy

packages.txt

@@ -0,0 +1 @@
+libpq-dev

pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "cashy"
+version = "1.0.0"
+description = "AI-powered financial advisor using LangGraph + LangChain + HuggingFace"
+requires-python = ">=3.10"
+dependencies = [
+    # Core agent framework
+    "langgraph>=0.2",
+    "langchain>=0.3",
+    "langchain-core>=0.3",
+    "langchain-huggingface>=0.1",
+
+    # LLM providers
+    "huggingface-hub>=0.20",
+    "langchain-openai>=0.3",
+    "langchain-anthropic>=0.3",
+    "langchain-google-genai>=2.0",
+
+    # Database (psycopg2 for tools, psycopg v3 for checkpointer)
+    "psycopg2-binary>=2.9",
+    "psycopg[binary]>=3.1",
+    "langgraph-checkpoint-postgres>=2.0",
+
+    # UI + charts
+    "gradio>=4.0",
+    "matplotlib>=3.8",
+
+    # Evaluation & tracing
+    "langsmith>=0.1",
+
+    # Config
+    "python-dotenv>=1.0",
+    "pydantic>=2.0",
+    "pydantic-settings>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4",
+    "pytest-cov>=4.0",
+    "ruff>=0.1",
+]
+experiment = [
+    "transformers",
+    "torch",
+    "pandas<3",
+]

requirements.txt

@@ -0,0 +1,365 @@
+# This file was autogenerated by uv via the following command:
+#    uv export --no-hashes --no-dev
+aiofiles==24.1.0
+    # via gradio
+annotated-doc==0.0.4
+    # via fastapi
+annotated-types==0.7.0
+    # via pydantic
+anthropic==0.79.0
+    # via langchain-anthropic
+anyio==4.12.1
+    # via
+    #   anthropic
+    #   google-genai
+    #   gradio
+    #   httpx
+    #   openai
+    #   starlette
+audioop-lts==0.2.2 ; python_full_version >= '3.13'
+    # via gradio
+brotli==1.2.0
+    # via gradio
+certifi==2026.1.4
+    # via
+    #   httpcore
+    #   httpx
+    #   requests
+cffi==2.0.0 ; platform_python_implementation != 'PyPy'
+    # via cryptography
+charset-normalizer==3.4.4
+    # via requests
+click==8.3.1
+    # via
+    #   typer
+    #   uvicorn
+colorama==0.4.6 ; sys_platform == 'win32'
+    # via
+    #   click
+    #   tqdm
+contourpy==1.3.2 ; python_full_version < '3.11'
+    # via matplotlib
+contourpy==1.3.3 ; python_full_version >= '3.11'
+    # via matplotlib
+cryptography==46.0.5
+    # via google-auth
+cycler==0.12.1
+    # via matplotlib
+distro==1.9.0
+    # via
+    #   anthropic
+    #   google-genai
+    #   openai
+docstring-parser==0.17.0
+    # via anthropic
+exceptiongroup==1.3.1 ; python_full_version < '3.11'
+    # via anyio
+fastapi==0.128.6
+    # via gradio
+ffmpy==1.0.0
+    # via gradio
+filelock==3.20.3
+    # via huggingface-hub
+filetype==1.2.0
+    # via langchain-google-genai
+fonttools==4.61.1
+    # via matplotlib
+fsspec==2026.2.0
+    # via
+    #   gradio-client
+    #   huggingface-hub
+google-auth==2.48.0
+    # via google-genai
+google-genai==1.63.0
+    # via langchain-google-genai
+gradio==6.5.1
+    # via cashy
+gradio-client==2.0.3
+    # via gradio
+groovy==0.1.2
+    # via gradio
+h11==0.16.0
+    # via
+    #   httpcore
+    #   uvicorn
+hf-xet==1.2.0 ; platform_machine == 'aarch64' or platform_machine == 'amd64' or platform_machine == 'arm64' or platform_machine == 'x86_64'
+    # via huggingface-hub
+httpcore==1.0.9
+    # via httpx
+httpx==0.28.1
+    # via
+    #   anthropic
+    #   google-genai
+    #   gradio
+    #   gradio-client
+    #   langgraph-sdk
+    #   langsmith
+    #   openai
+    #   safehttpx
+huggingface-hub==0.36.2
+    # via
+    #   cashy
+    #   gradio
+    #   gradio-client
+    #   langchain-huggingface
+    #   tokenizers
+idna==3.11
+    # via
+    #   anyio
+    #   httpx
+    #   requests
+jinja2==3.1.6
+    # via gradio
+jiter==0.13.0
+    # via
+    #   anthropic
+    #   openai
+jsonpatch==1.33
+    # via langchain-core
+jsonpointer==3.0.0
+    # via jsonpatch
+kiwisolver==1.4.9
+    # via matplotlib
+langchain==1.2.9
+    # via cashy
+langchain-anthropic==1.3.3
+    # via cashy
+langchain-core==1.2.13
+    # via
+    #   cashy
+    #   langchain
+    #   langchain-anthropic
+    #   langchain-google-genai
+    #   langchain-huggingface
+    #   langchain-openai
+    #   langgraph
+    #   langgraph-checkpoint
+    #   langgraph-prebuilt
+langchain-google-genai==4.2.0
+    # via cashy
+langchain-huggingface==1.2.0
+    # via cashy
+langchain-openai==1.1.9
+    # via cashy
+langgraph==1.0.8
+    # via
+    #   cashy
+    #   langchain
+langgraph-checkpoint==4.0.0
+    # via
+    #   langgraph
+    #   langgraph-checkpoint-postgres
+    #   langgraph-prebuilt
+langgraph-checkpoint-postgres==3.0.4
+    # via cashy
+langgraph-prebuilt==1.0.7
+    # via langgraph
+langgraph-sdk==0.3.4
+    # via langgraph
+langsmith==0.7.0
+    # via
+    #   cashy
+    #   langchain-core
+markdown-it-py==4.0.0
+    # via rich
+markupsafe==3.0.3
+    # via
+    #   gradio
+    #   jinja2
+matplotlib==3.10.8
+    # via cashy
+mdurl==0.1.2
+    # via markdown-it-py
+numpy==2.2.6 ; python_full_version < '3.11'
+    # via
+    #   contourpy
+    #   gradio
+    #   matplotlib
+    #   pandas
+numpy==2.4.2 ; python_full_version >= '3.11'
+    # via
+    #   contourpy
+    #   gradio
+    #   matplotlib
+    #   pandas
+openai==2.21.0
+    # via langchain-openai
+orjson==3.11.7
+    # via
+    #   gradio
+    #   langgraph-checkpoint-postgres
+    #   langgraph-sdk
+    #   langsmith
+ormsgpack==1.12.2
+    # via langgraph-checkpoint
+packaging==26.0
+    # via
+    #   gradio
+    #   gradio-client
+    #   huggingface-hub
+    #   langchain-core
+    #   langsmith
+    #   matplotlib
+pandas==2.3.3
+    # via gradio
+pillow==12.1.0
+    # via
+    #   gradio
+    #   matplotlib
+psycopg==3.3.2
+    # via
+    #   cashy
+    #   langgraph-checkpoint-postgres
+psycopg-binary==3.3.2 ; implementation_name != 'pypy'
+    # via psycopg
+psycopg-pool==3.3.0
+    # via langgraph-checkpoint-postgres
+psycopg2-binary==2.9.11
+    # via cashy
+pyasn1==0.6.2
+    # via
+    #   pyasn1-modules
+    #   rsa
+pyasn1-modules==0.4.2
+    # via google-auth
+pycparser==3.0 ; implementation_name != 'PyPy' and platform_python_implementation != 'PyPy'
+    # via cffi
+pydantic==2.12.5
+    # via
+    #   anthropic
+    #   cashy
+    #   fastapi
+    #   google-genai
+    #   gradio
+    #   langchain
+    #   langchain-anthropic
+    #   langchain-core
+    #   langchain-google-genai
+    #   langgraph
+    #   langsmith
+    #   openai
+    #   pydantic-settings
+pydantic-core==2.41.5
+    # via pydantic
+pydantic-settings==2.12.0
+    # via cashy
+pydub==0.25.1
+    # via gradio
+pygments==2.19.2
+    # via rich
+pyparsing==3.3.2
+    # via matplotlib
+python-dateutil==2.9.0.post0
+    # via
+    #   matplotlib
+    #   pandas
+python-dotenv==1.2.1
+    # via
+    #   cashy
+    #   pydantic-settings
+python-multipart==0.0.22
+    # via gradio
+pytz==2025.2
+    # via
+    #   gradio
+    #   pandas
+pyyaml==6.0.3
+    # via
+    #   gradio
+    #   huggingface-hub
+    #   langchain-core
+regex==2026.1.15
+    # via tiktoken
+requests==2.32.5
+    # via
+    #   google-auth
+    #   google-genai
+    #   huggingface-hub
+    #   langsmith
+    #   requests-toolbelt
+    #   tiktoken
+requests-toolbelt==1.0.0
+    # via langsmith
+rich==14.3.2
+    # via typer
+rsa==4.9.1
+    # via google-auth
+safehttpx==0.1.7
+    # via gradio
+semantic-version==2.10.0
+    # via gradio
+shellingham==1.5.4
+    # via typer
+six==1.17.0
+    # via python-dateutil
+sniffio==1.3.1
+    # via
+    #   anthropic
+    #   google-genai
+    #   openai
+starlette==0.52.1
+    # via
+    #   fastapi
+    #   gradio
+tenacity==9.1.4
+    # via
+    #   google-genai
+    #   langchain-core
+tiktoken==0.12.0
+    # via langchain-openai
+tokenizers==0.22.2
+    # via langchain-huggingface
+tomlkit==0.13.3
+    # via gradio
+tqdm==4.67.3
+    # via
+    #   huggingface-hub
+    #   openai
+typer==0.21.1
+    # via gradio
+typing-extensions==4.15.0
+    # via
+    #   anthropic
+    #   anyio
+    #   cryptography
+    #   exceptiongroup
+    #   fastapi
+    #   google-genai
+    #   gradio
+    #   gradio-client
+    #   huggingface-hub
+    #   langchain-core
+    #   openai
+    #   psycopg
+    #   psycopg-pool
+    #   pydantic
+    #   pydantic-core
+    #   starlette
+    #   typer
+    #   typing-inspection
+    #   uvicorn
+typing-inspection==0.4.2
+    # via
+    #   fastapi
+    #   pydantic
+    #   pydantic-settings
+tzdata==2025.3
+    # via
+    #   pandas
+    #   psycopg
+urllib3==2.6.3
+    # via requests
+uuid-utils==0.14.0
+    # via
+    #   langchain-core
+    #   langsmith
+uvicorn==0.40.0
+    # via gradio
+websockets==15.0.1
+    # via google-genai
+xxhash==3.6.0
+    # via
+    #   langgraph
+    #   langsmith
+zstandard==0.25.0
+    # via langsmith

scripts/evaluators.py

@@ -0,0 +1,71 @@
+"""
+Code-based evaluators for Cashy LangSmith experiments.
+
+Each evaluator uses the new-style signature (outputs, reference_outputs)
+supported in langsmith 0.7.0. They receive:
+  - outputs: dict returned by the target function (response, tools_called, tool_args, error)
+  - reference_outputs: dict from the dataset example's outputs field
+"""
+
+
+def tool_usage(outputs: dict, reference_outputs: dict) -> dict:
+    """Check if at least one expected tool was called."""
+    expected = reference_outputs.get("expected_tools", [])
+    actual = outputs.get("tools_called", [])
+
+    if not expected:
+        score = 1
+    else:
+        score = 1 if any(t in actual for t in expected) else 0
+
+    return {"key": "tool_usage", "score": score}
+
+
+def content_contains(outputs: dict, reference_outputs: dict) -> dict:
+    """Check if all expected substrings appear in the response (case-insensitive)."""
+    expected = reference_outputs.get("expected_output_contains", [])
+    response = (outputs.get("response") or "").lower()
+
+    if not expected:
+        score = 1
+    else:
+        score = 1 if all(s.lower() in response for s in expected) else 0
+
+    return {"key": "content_contains", "score": score}
+
+
+def tool_args_match(outputs: dict, reference_outputs: dict) -> dict:
+    """Check if tool calls contain the expected arguments.
+
+    Compares each expected key-value pair against all actual tool call args.
+    Score = fraction of expected pairs that were found in any tool call.
+    """
+    expected_args = reference_outputs.get("expected_tool_args", {})
+    actual_args_list = outputs.get("tool_args", [])
+
+    if not expected_args:
+        return {"key": "tool_args_match", "score": 1}
+
+    matched = 0
+    total = len(expected_args)
+
+    for key, expected_val in expected_args.items():
+        for actual_args in actual_args_list:
+            actual_val = actual_args.get(key)
+            if actual_val is not None and str(actual_val).lower() == str(expected_val).lower():
+                matched += 1
+                break
+
+    score = matched / total if total > 0 else 1
+    return {"key": "tool_args_match", "score": score}
+
+
+def no_error(outputs: dict) -> dict:
+    """Check that no error occurred during agent execution."""
+    error = outputs.get("error")
+    score = 1 if not error else 0
+    return {"key": "no_error", "score": score}
+
+
+# List of all evaluators for easy import
+all_evaluators = [tool_usage, content_contains, tool_args_match, no_error]

scripts/experiment_table_qa.py

@@ -0,0 +1,222 @@
+"""
+Experiment: Local Table QA with TAPAS/TAPEX models on financial data.
+
+Runs a table QA model locally on CPU to answer questions about data
+from the PostgreSQL financial database.
+
+Supports two architectures:
+  - TAPAS (google/tapas-*): cell selection + aggregation
+  - TAPEX (microsoft/tapex-*): seq2seq text generation (BART-based)
+
+Run:
+    uv run --extra experiment python scripts/experiment_table_qa.py
+    uv run --extra experiment python scripts/experiment_table_qa.py --model google/tapas-small-finetuned-wtq
+    uv run --extra experiment python scripts/experiment_table_qa.py --model microsoft/tapex-base-finetuned-wtq
+"""
+
+import argparse
+import json
+import sys
+import time
+from datetime import datetime
+from pathlib import Path
+
+# Add project root to path so we can import src.*
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+import pandas as pd
+
+from src.db.connection import get_connection
+
+DEFAULT_MODEL = "google/tapas-mini-finetuned-wtq"
+
+QUERY = """
+    SELECT
+        transaction_date::text AS date,
+        transaction_description AS description,
+        category_name AS category,
+        entry_amount::text AS amount,
+        account_name AS account
+    FROM v_transaction_details
+    WHERE category_name IS NOT NULL
+    ORDER BY transaction_date DESC
+    LIMIT 15
+"""
+
+QUESTIONS = [
+    "What is the total amount?",
+    "Which category has the highest amount?",
+    "How many transactions are there?",
+]
+
+RESULTS_FILE = Path(__file__).resolve().parent.parent / "eval_cases" / "table_qa_results.jsonl"
+
+
+def is_tapex(model_name: str) -> bool:
+    return "tapex" in model_name.lower()
+
+
+def fetch_table() -> pd.DataFrame:
+    print("[STEP 1] Connecting to PostgreSQL...")
+    with get_connection() as conn:
+        print(f"  -> Connected to: {conn.dsn}")
+        print(f"  -> Executing query:\n{QUERY.strip()}")
+
+        with conn.cursor() as cur:
+            cur.execute(QUERY)
+            columns = [desc[0] for desc in cur.description]
+            rows = cur.fetchall()
+
+    print(f"  -> Raw result: {len(rows)} rows, {len(columns)} columns")
+    print(f"  -> Columns: {columns}")
+
+    # Build DataFrame from dict of lists — pandas 2.x defaults to object dtype.
+    # TAPAS tokenizer mutates cells via iloc with its internal Cell namedtuple,
+    # which requires object dtype (incompatible with pandas 3.0 StringDtype).
+    data = {col: [str(row[i]) for row in rows] for i, col in enumerate(columns)}
+    df = pd.DataFrame.from_dict(data)
+
+    print(f"  -> Dtypes (should be object):\n{df.dtypes.to_string()}")
+    print(f"  -> Sample row: {dict(df.iloc[0])}")
+    print()
+    return df
+
+
+def load_tapas(model_name):
+    from transformers import pipeline
+
+    tqa = pipeline("table-question-answering", model=model_name, device=-1)
+    param_count = sum(p.numel() for p in tqa.model.parameters())
+    print(f"  -> Architecture: TAPAS (cell selection + aggregation)")
+    print(f"  -> Model class: {type(tqa.model).__name__}")
+    print(f"  -> Tokenizer: {type(tqa.tokenizer).__name__}")
+    print(f"  -> Model params: {param_count:,}")
+    return tqa, param_count
+
+
+def load_tapex(model_name):
+    from transformers import BartForConditionalGeneration, TapexTokenizer
+
+    tokenizer = TapexTokenizer.from_pretrained(model_name)
+    model = BartForConditionalGeneration.from_pretrained(model_name)
+    param_count = sum(p.numel() for p in model.parameters())
+    print(f"  -> Architecture: TAPEX (seq2seq text generation, BART-based)")
+    print(f"  -> Model class: {type(model).__name__}")
+    print(f"  -> Tokenizer: {type(tokenizer).__name__}")
+    print(f"  -> Model params: {param_count:,}")
+    return (tokenizer, model), param_count
+
+
+def run_tapas(tqa, table, query):
+    result = tqa(table=table, query=query)
+    return {
+        "answer": result["answer"],
+        "cells": result.get("cells", []),
+        "aggregator": result.get("aggregator", "NONE"),
+    }
+
+
+def run_tapex(tapex_pair, table, query):
+    tokenizer, model = tapex_pair
+    encoding = tokenizer(table=table, query=query, return_tensors="pt", truncation=True)
+    print(f"  -> Input token count: {encoding['input_ids'].shape[1]}")
+    outputs = model.generate(**encoding, max_new_tokens=50)
+    decoded = tokenizer.batch_decode(outputs, skip_special_tokens=True)
+    answer = decoded[0] if decoded else ""
+    return {
+        "answer": answer,
+        "cells": [],
+        "aggregator": "seq2seq",
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Table QA experiment (TAPAS/TAPEX)")
+    parser.add_argument("--model", default=DEFAULT_MODEL, help="HuggingFace model name")
+    args = parser.parse_args()
+
+    model_name = args.model
+    use_tapex = is_tapex(model_name)
+    run_results = {
+        "timestamp": datetime.now().isoformat(),
+        "model": model_name,
+        "architecture": "tapex" if use_tapex else "tapas",
+        "questions": [],
+    }
+
+    # --- Model loading ---
+    print("=" * 60)
+    print("[STEP 2] Loading model")
+    print("=" * 60)
+    print(f"  -> Model: {model_name}")
+    print(f"  -> Device: CPU")
+    print()
+
+    t0 = time.time()
+    if use_tapex:
+        model_obj, param_count = load_tapex(model_name)
+    else:
+        model_obj, param_count = load_tapas(model_name)
+    load_time = time.time() - t0
+
+    print(f"  -> Load time: {load_time:.2f}s")
+    print()
+
+    run_results["params"] = param_count
+    run_results["load_time_s"] = round(load_time, 2)
+
+    # --- Data fetching ---
+    print("=" * 60)
+    print("[STEP 1] Fetching data from PostgreSQL")
+    print("=" * 60)
+    table = fetch_table()
+
+    # --- Display table ---
+    print("=" * 60)
+    print("TABLE (15 most recent transactions)")
+    print("=" * 60)
+    print(table.to_string(index=False))
+    print()
+
+    # --- Q&A ---
+    run_fn = run_tapex if use_tapex else run_tapas
+
+    print("=" * 60)
+    print("[STEP 3] Running Table QA inference")
+    print("=" * 60)
+    for i, q in enumerate(QUESTIONS, 1):
+        print(f"\n--- Question {i}/{len(QUESTIONS)} ---")
+        print(f"  -> Input query: {q!r}")
+        print(f"  -> Input table shape: {table.shape}")
+
+        t0 = time.time()
+        result = run_fn(model_obj, table, q)
+        inference_time = time.time() - t0
+
+        print(f"  -> Answer: {result['answer']}")
+        print(f"  -> Cells: {result.get('cells', [])}")
+        print(f"  -> Aggregator: {result.get('aggregator', 'N/A')}")
+        print(f"  -> Inference time: {inference_time:.3f}s")
+
+        run_results["questions"].append({
+            "query": q,
+            "answer": result["answer"],
+            "cells": result.get("cells", []),
+            "aggregator": result.get("aggregator", "N/A"),
+            "inference_time_s": round(inference_time, 3),
+        })
+    print()
+
+    # --- Save results ---
+    RESULTS_FILE.parent.mkdir(parents=True, exist_ok=True)
+    with open(RESULTS_FILE, "a") as f:
+        f.write(json.dumps(run_results, ensure_ascii=False) + "\n")
+    print(f"Results appended to: {RESULTS_FILE}")
+
+    print("=" * 60)
+    print("Experiment complete.")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

scripts/run_eval.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""
+Run LangSmith evaluation experiments for the Cashy agent.
+
+Usage:
+    uv run python scripts/run_eval.py                                    # Run experiment (default dataset + prefix)
+    uv run python scripts/run_eval.py --prefix cashy-new-prompt          # A/B test with custom prefix
+    uv run python scripts/run_eval.py --dataset cashy-eval-v2.0          # Use specific dataset
+    uv run python scripts/run_eval.py --upload                           # Upload eval cases to LangSmith
+    uv run python scripts/run_eval.py --upload --file eval_cases/eval_cases_v1.json  # Upload specific file
+"""
+
+import json
+import logging
+import argparse
+import sys
+from pathlib import Path
+
+# Add project root to path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from dotenv import load_dotenv
+load_dotenv(Path(__file__).parent.parent / ".env")
+
+from langsmith.evaluation import evaluate
+from langsmith import Client
+from langchain_core.messages import HumanMessage
+from src.agent.graph import create_agent
+from scripts.evaluators import all_evaluators
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(name)-12s] %(levelname)-7s %(message)s",
+    datefmt="%H:%M:%S",
+)
+for name in ("httpx", "httpcore", "urllib3", "hf_transfer"):
+    logging.getLogger(name).setLevel(logging.WARNING)
+
+logger = logging.getLogger("cashy.eval")
+
+EVAL_FILE = Path(__file__).parent.parent / "eval_cases" / "eval_cases_v2.json"
+DEFAULT_DATASET = "cashy-eval-v2.0"
+DEFAULT_PREFIX = "cashy-baseline"
+
+
+def make_target(agent):
+    """Create a target function that wraps the agent for langsmith evaluate()."""
+
+    def run_agent(inputs: dict) -> dict:
+        try:
+            result = agent.invoke({"messages": [HumanMessage(content=inputs["input"])]})
+            response = result["messages"][-1].content
+
+            tools_called = []
+            tool_args = []
+            for msg in result["messages"]:
+                if hasattr(msg, "tool_calls") and msg.tool_calls:
+                    for tc in msg.tool_calls:
+                        tools_called.append(tc["name"])
+                        tool_args.append(tc.get("args", {}))
+
+            return {
+                "response": response,
+                "tools_called": tools_called,
+                "tool_args": tool_args,
+                "error": None,
+            }
+        except Exception as e:
+            logger.error("Agent error: %s", e)
+            return {
+                "response": None,
+                "tools_called": [],
+                "tool_args": [],
+                "error": str(e),
+            }
+
+    return run_agent
+
+
+def upload_to_langsmith(eval_data: dict):
+    """Upload eval cases as a LangSmith dataset with enriched outputs."""
+    client = Client()
+    version = eval_data["metadata"]["version"]
+    dataset_name = f"cashy-eval-v{version}"
+
+    try:
+        dataset = client.create_dataset(
+            dataset_name=dataset_name,
+            description=eval_data["metadata"]["description"],
+        )
+        logger.info("Created dataset: %s", dataset_name)
+    except Exception:
+        dataset = client.read_dataset(dataset_name=dataset_name)
+        logger.info("Dataset already exists: %s", dataset_name)
+
+    for case in eval_data["cases"]:
+        client.create_example(
+            inputs={"input": case["input"]},
+            outputs={
+                "expected_tools": case.get("expected_tools", []),
+                "expected_output_contains": case.get("expected_output_contains", []),
+                "expected_tool_args": case.get("expected_tool_args", {}),
+            },
+            dataset_id=dataset.id,
+            metadata={
+                "category": case.get("category"),
+                "case_id": case["id"],
+                "criteria": case.get("evaluation_criteria", []),
+            },
+        )
+    logger.info("Uploaded %d examples to dataset '%s'", len(eval_data["cases"]), dataset_name)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Run Cashy LangSmith evaluation")
+    parser.add_argument("--dataset", default=DEFAULT_DATASET, help="LangSmith dataset name")
+    parser.add_argument("--prefix", default=DEFAULT_PREFIX, help="Experiment prefix (for A/B naming)")
+    parser.add_argument("--upload", action="store_true", help="Upload eval cases to LangSmith dataset")
+    parser.add_argument("--file", default=str(EVAL_FILE), help="Local eval cases JSON file")
+    args = parser.parse_args()
+
+    if args.upload:
+        eval_data = json.loads(Path(args.file).read_text())
+        logger.info("Loaded %d eval cases from %s", len(eval_data["cases"]), args.file)
+        upload_to_langsmith(eval_data)
+        return
+
+    logger.info("Creating agent...")
+    agent = create_agent()
+    target = make_target(agent)
+
+    logger.info("Running experiment '%s' on dataset '%s'...", args.prefix, args.dataset)
+    results = evaluate(
+        target,
+        data=args.dataset,
+        evaluators=all_evaluators,
+        experiment_prefix=args.prefix,
+        max_concurrency=0,
+    )
+
+    print("\n" + "=" * 60)
+    print(f"Experiment '{args.prefix}' complete.")
+    print(f"View results in LangSmith: Datasets > {args.dataset} > Experiments")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

scripts/sanitize_agent_export.py

@@ -0,0 +1,240 @@
+#!/usr/bin/env python3
+"""
+Sanitize Langflow agent exports by removing sensitive credentials.
+
+Usage:
+    python scripts/sanitize_agent_export.py <input_file> [output_file]
+
+If output_file is not provided, it will create a sanitized version with '_sanitized' suffix.
+"""
+
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Tuple
+
+
+# Patterns that indicate sensitive data
+SENSITIVE_PATTERNS = [
+    r'sk-[a-zA-Z0-9]{20,}',  # OpenAI API keys
+    r'sk-proj-[a-zA-Z0-9]{20,}',  # OpenAI project API keys
+    r'postgresql://[^:]+:[^@]+@',  # PostgreSQL connection strings with password
+    r'mongodb://[^:]+:[^@]+@',  # MongoDB connection strings with password
+    r'Bearer\s+[a-zA-Z0-9\-._~+/]+=*',  # Bearer tokens
+    r'[a-zA-Z0-9]{32,}',  # Generic long alphanumeric strings (likely tokens)
+]
+
+# Keys that typically contain sensitive data
+SENSITIVE_KEYS = [
+    'api_key',
+    'apikey',
+    'openai_api_key',
+    'langsmith_api_key',
+    'password',
+    'secret',
+    'secret_key',
+    'token',
+    'bearer',
+    'credential',
+    'auth',
+    'authorization',
+    'connection_string',
+    'database_url',
+    'db_password',
+]
+
+# Replacement values for different credential types
+REPLACEMENTS = {
+    'api_key': '${OPENAI_API_KEY}',
+    'apikey': '${API_KEY}',
+    'openai_api_key': '${OPENAI_API_KEY}',
+    'langsmith_api_key': '${LANGSMITH_API_KEY}',
+    'password': '${DB_PASSWORD}',
+    'secret': '${SECRET_KEY}',
+    'secret_key': '${SECRET_KEY}',
+    'token': '${AUTH_TOKEN}',
+    'bearer': '${BEARER_TOKEN}',
+    'credential': '${CREDENTIAL}',
+    'auth': '${AUTH_KEY}',
+    'authorization': '${AUTHORIZATION}',
+    'connection_string': '${DATABASE_URL}',
+    'database_url': '${DATABASE_URL}',
+    'db_password': '${DB_PASSWORD}',
+}
+
+
+class CredentialDetector:
+    """Detect and report potential credentials in data structures."""
+
+    def __init__(self):
+        self.findings: List[Tuple[str, str, str]] = []  # (path, key, value)
+
+    def scan_value(self, value: str, path: str = "") -> bool:
+        """Check if a value matches sensitive patterns."""
+        if not isinstance(value, str) or len(value) < 8:
+            return False
+
+        for pattern in SENSITIVE_PATTERNS:
+            if re.search(pattern, value, re.IGNORECASE):
+                return True
+        return False
+
+    def scan_dict(self, data: Dict[str, Any], path: str = "") -> None:
+        """Recursively scan dictionary for sensitive data."""
+        for key, value in data.items():
+            current_path = f"{path}.{key}" if path else key
+
+            # Check if key name suggests sensitive data
+            if any(sensitive in key.lower() for sensitive in SENSITIVE_KEYS):
+                if isinstance(value, str) and value:
+                    self.findings.append((current_path, key, value))
+
+            # Check if value matches sensitive patterns
+            elif isinstance(value, str) and self.scan_value(value, current_path):
+                self.findings.append((current_path, key, value))
+
+            # Recurse into nested structures
+            elif isinstance(value, dict):
+                self.scan_dict(value, current_path)
+            elif isinstance(value, list):
+                self.scan_list(value, current_path)
+
+    def scan_list(self, data: List[Any], path: str = "") -> None:
+        """Recursively scan list for sensitive data."""
+        for i, item in enumerate(data):
+            current_path = f"{path}[{i}]"
+
+            if isinstance(item, dict):
+                self.scan_dict(item, current_path)
+            elif isinstance(item, list):
+                self.scan_list(item, current_path)
+            elif isinstance(item, str) and self.scan_value(item, current_path):
+                self.findings.append((current_path, f"item_{i}", item))
+
+
+def sanitize_value(key: str, value: str) -> str:
+    """Replace sensitive value with appropriate placeholder."""
+    key_lower = key.lower()
+
+    # Use specific replacement if key matches known pattern
+    for sensitive_key, replacement in REPLACEMENTS.items():
+        if sensitive_key in key_lower:
+            return replacement
+
+    # Default replacement for unknown sensitive data
+    return "${CREDENTIAL}"
+
+
+def sanitize_dict(data: Dict[str, Any]) -> Dict[str, Any]:
+    """Recursively sanitize dictionary by replacing sensitive values."""
+    sanitized = {}
+
+    for key, value in data.items():
+        # Check if key suggests sensitive data
+        if any(sensitive in key.lower() for sensitive in SENSITIVE_KEYS):
+            if isinstance(value, str) and value:
+                sanitized[key] = sanitize_value(key, value)
+            else:
+                sanitized[key] = value
+
+        # Recurse into nested structures
+        elif isinstance(value, dict):
+            sanitized[key] = sanitize_dict(value)
+        elif isinstance(value, list):
+            sanitized[key] = sanitize_list(value)
+        else:
+            sanitized[key] = value
+
+    return sanitized
+
+
+def sanitize_list(data: List[Any]) -> List[Any]:
+    """Recursively sanitize list by replacing sensitive values."""
+    sanitized = []
+
+    for item in data:
+        if isinstance(item, dict):
+            sanitized.append(sanitize_dict(item))
+        elif isinstance(item, list):
+            sanitized.append(sanitize_list(item))
+        else:
+            sanitized.append(item)
+
+    return sanitized
+
+
+def sanitize_agent_export(input_file: Path, output_file: Path = None) -> bool:
+    """
+    Sanitize Langflow agent export by removing credentials.
+
+    Returns True if credentials were found and sanitized, False otherwise.
+    """
+    # Read input file
+    try:
+        with open(input_file, 'r') as f:
+            data = json.load(f)
+    except Exception as e:
+        print(f"❌ Error reading {input_file}: {e}")
+        return False
+
+    # Scan for credentials
+    detector = CredentialDetector()
+    detector.scan_dict(data)
+
+    if not detector.findings:
+        print(f"✅ No credentials detected in {input_file}")
+        return False
+
+    # Report findings
+    print(f"⚠️  Found {len(detector.findings)} potential credential(s) in {input_file}:")
+    for path, key, value in detector.findings:
+        # Mask the value for display
+        masked = value[:8] + "..." if len(value) > 8 else "***"
+        print(f"   - {path}: {key} = {masked}")
+
+    # Sanitize data
+    sanitized_data = sanitize_dict(data)
+
+    # Determine output file
+    if output_file is None:
+        output_file = input_file.parent / f"{input_file.stem}_sanitized{input_file.suffix}"
+
+    # Write sanitized output
+    try:
+        with open(output_file, 'w') as f:
+            json.dump(sanitized_data, f, indent=2)
+        print(f"✅ Sanitized version saved to: {output_file}")
+        return True
+    except Exception as e:
+        print(f"❌ Error writing {output_file}: {e}")
+        return False
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python sanitize_agent_export.py <input_file> [output_file]")
+        sys.exit(1)
+
+    input_file = Path(sys.argv[1])
+    output_file = Path(sys.argv[2]) if len(sys.argv) > 2 else None
+
+    if not input_file.exists():
+        print(f"❌ Error: {input_file} does not exist")
+        sys.exit(1)
+
+    # Run sanitization
+    found_credentials = sanitize_agent_export(input_file, output_file)
+
+    if found_credentials:
+        print("\n⚠️  WARNING: Credentials were found and replaced with placeholders.")
+        print("   Review the sanitized file before committing to Git.")
+        print("   Make sure to use environment variables in Langflow for all credentials.")
+        sys.exit(1)  # Exit with error code to prevent accidental commits
+    else:
+        print("\n✅ File is safe to commit.")
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

scripts/seed_demo_db.sql

@@ -0,0 +1,1091 @@
+-- =============================================================================
+-- Cashy Demo Database Seed Script
+-- US Freelancer Persona — English Language
+--
+-- Usage:
+--   createdb -U postgres cashy_demo
+--   psql -U postgres -d cashy_demo -f scripts/seed_demo_db.sql
+--
+-- To reset: dropdb -U postgres cashy_demo && createdb -U postgres cashy_demo && psql -U postgres -d cashy_demo -f scripts/seed_demo_db.sql
+-- =============================================================================
+
+-- Grant privileges to the application user
+GRANT ALL PRIVILEGES ON DATABASE cashy_demo TO financial_advisor;
+
+-- =============================================================================
+-- 1. TRIGGER FUNCTION
+-- =============================================================================
+
+CREATE OR REPLACE FUNCTION update_updated_at_column()
+RETURNS TRIGGER AS $$
+BEGIN
+    NEW.updated_at = CURRENT_TIMESTAMP;
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+-- =============================================================================
+-- 2. TABLES (11)
+-- =============================================================================
+
+-- account_types
+CREATE TABLE account_types (
+    id SERIAL PRIMARY KEY,
+    name VARCHAR(100) NOT NULL,
+    description TEXT,
+    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
+);
+CREATE TRIGGER trigger_account_types_updated_at
+    BEFORE UPDATE ON account_types FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
+
+-- accounts
+CREATE TABLE accounts (
+    id SERIAL PRIMARY KEY,
+    name VARCHAR(200) NOT NULL,
+    account_type_id INTEGER NOT NULL REFERENCES account_types(id),
+    current_balance NUMERIC(15,2) NOT NULL DEFAULT 0.00,
+    is_active BOOLEAN NOT NULL DEFAULT true,
+    account_number VARCHAR(50),
+    institution VARCHAR(100),
+    currency VARCHAR(3) NOT NULL DEFAULT 'USD',
+    notes TEXT,
+    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
+    credit_limit NUMERIC(15,2) DEFAULT NULL,
+    opening_balance NUMERIC(15,2) NOT NULL DEFAULT 0.00,
+    CONSTRAINT unique_account_name UNIQUE (name)
+);
+CREATE INDEX idx_accounts_name ON accounts(name);
+CREATE INDEX idx_accounts_type ON accounts(account_type_id);
+CREATE INDEX idx_accounts_active ON accounts(is_active);
+CREATE TRIGGER trigger_accounts_updated_at
+    BEFORE UPDATE ON accounts FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
+
+-- categories
+CREATE TABLE categories (
+    id SERIAL PRIMARY KEY,
+    name VARCHAR(200) NOT NULL,
+    parent_category_id INTEGER REFERENCES categories(id),
+    category_type VARCHAR(20) NOT NULL,
+    description TEXT,
+    is_active BOOLEAN NOT NULL DEFAULT true,
+    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
+);
+CREATE INDEX idx_categories_type ON categories(category_type);
+CREATE INDEX idx_categories_parent ON categories(parent_category_id);
+CREATE TRIGGER trigger_categories_updated_at
+    BEFORE UPDATE ON categories FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
+
+-- transactions
+CREATE TABLE transactions (
+    id SERIAL PRIMARY KEY,
+    transaction_date DATE NOT NULL,
+    description VARCHAR(500) NOT NULL,
+    transaction_type VARCHAR(20) NOT NULL,
+    total_amount NUMERIC(15,2) NOT NULL,
+    reference_number VARCHAR(100),
+    notes TEXT,
+    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
+    CONSTRAINT transactions_transaction_type_check
+        CHECK (transaction_type IN ('income', 'expense', 'transfer', 'adjustment')),
+    CONSTRAINT adjustment_requires_notes
+        CHECK (transaction_type <> 'adjustment' OR notes IS NOT NULL)
+);
+CREATE INDEX idx_transactions_date ON transactions(transaction_date);
+CREATE INDEX idx_transactions_type ON transactions(transaction_type);
+CREATE INDEX idx_transactions_date_type ON transactions(transaction_date, transaction_type);
+CREATE TRIGGER trigger_transactions_updated_at
+    BEFORE UPDATE ON transactions FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
+
+-- transaction_entries
+CREATE TABLE transaction_entries (
+    id SERIAL PRIMARY KEY,
+    transaction_id INTEGER NOT NULL REFERENCES transactions(id) ON DELETE CASCADE,
+    account_id INTEGER NOT NULL REFERENCES accounts(id),
+    category_id INTEGER REFERENCES categories(id),
+    amount NUMERIC(15,2) NOT NULL,
+    entry_type VARCHAR(10) NOT NULL,
+    description VARCHAR(500),
+    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
+);
+CREATE INDEX idx_entries_transaction ON transaction_entries(transaction_id);
+CREATE INDEX idx_entries_account ON transaction_entries(account_id);
+CREATE INDEX idx_entries_category ON transaction_entries(category_id);
+
+-- budgets
+CREATE TABLE budgets (
+    id SERIAL PRIMARY KEY,
+    category_id INTEGER NOT NULL REFERENCES categories(id),
+    month_year DATE NOT NULL,
+    budgeted_amount NUMERIC(15,2) NOT NULL,
+    actual_amount NUMERIC(15,2) DEFAULT 0.00,
+    variance_amount NUMERIC(15,2) GENERATED ALWAYS AS (actual_amount - budgeted_amount) STORED,
+    variance_percentage NUMERIC(5,2) GENERATED ALWAYS AS (
+        CASE WHEN budgeted_amount = 0 THEN 0
+             ELSE ROUND((actual_amount - budgeted_amount) / budgeted_amount * 100, 2)
+        END
+    ) STORED,
+    notes TEXT,
+    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
+    CONSTRAINT unique_category_month UNIQUE (category_id, month_year)
+);
+CREATE INDEX idx_budgets_month ON budgets(month_year);
+CREATE INDEX idx_budgets_category ON budgets(category_id);
+CREATE INDEX idx_budgets_category_month ON budgets(category_id, month_year);
+CREATE TRIGGER trigger_budgets_updated_at
+    BEFORE UPDATE ON budgets FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
+
+-- budget_goals
+CREATE TABLE budget_goals (
+    id SERIAL PRIMARY KEY,
+    name VARCHAR(200) NOT NULL,
+    description TEXT,
+    target_amount NUMERIC(15,2) NOT NULL,
+    current_amount NUMERIC(15,2) NOT NULL DEFAULT 0.00,
+    target_date DATE,
+    goal_type VARCHAR(20) NOT NULL,
+    priority INTEGER,
+    is_active BOOLEAN NOT NULL DEFAULT true,
+    completion_percentage NUMERIC(5,2) GENERATED ALWAYS AS (
+        CASE WHEN target_amount = 0 THEN 0
+             ELSE ROUND(current_amount / target_amount * 100, 2)
+        END
+    ) STORED,
+    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
+    CONSTRAINT budget_goals_goal_type_check
+        CHECK (goal_type IN ('emergency_fund', 'savings', 'debt_payoff', 'investment', 'purchase', 'other')),
+    CONSTRAINT budget_goals_priority_check CHECK (priority >= 1 AND priority <= 10)
+);
+CREATE INDEX idx_budget_goals_active ON budget_goals(is_active);
+CREATE INDEX idx_budget_goals_type ON budget_goals(goal_type);
+CREATE INDEX idx_budget_goals_target_date ON budget_goals(target_date);
+CREATE TRIGGER trigger_budget_goals_updated_at
+    BEFORE UPDATE ON budget_goals FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
+
+-- goal_contributions
+CREATE TABLE goal_contributions (
+    id SERIAL PRIMARY KEY,
+    goal_id INTEGER NOT NULL REFERENCES budget_goals(id) ON DELETE CASCADE,
+    month_year DATE NOT NULL,
+    planned_amount NUMERIC(15,2) NOT NULL DEFAULT 0.00,
+    actual_amount NUMERIC(15,2) NOT NULL DEFAULT 0.00,
+    source_account_id INTEGER REFERENCES accounts(id),
+    notes TEXT,
+    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
+    CONSTRAINT goal_contributions_unique_goal_month UNIQUE (goal_id, month_year),
+    CONSTRAINT goal_contributions_planned_amount_check CHECK (planned_amount >= 0),
+    CONSTRAINT goal_contributions_actual_amount_check CHECK (actual_amount >= 0)
+);
+CREATE INDEX idx_goal_contributions_goal ON goal_contributions(goal_id);
+CREATE INDEX idx_goal_contributions_month ON goal_contributions(month_year);
+CREATE INDEX idx_goal_contributions_goal_month ON goal_contributions(goal_id, month_year);
+CREATE INDEX idx_goal_contributions_source_account ON goal_contributions(source_account_id);
+CREATE TRIGGER trigger_goal_contributions_updated_at
+    BEFORE UPDATE ON goal_contributions FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
+
+-- monthly_balances
+CREATE TABLE monthly_balances (
+    id SERIAL PRIMARY KEY,
+    account_id INTEGER NOT NULL REFERENCES accounts(id),
+    month_year DATE NOT NULL,
+    opening_balance NUMERIC(15,2) NOT NULL,
+    closing_balance NUMERIC(15,2) NOT NULL,
+    net_change NUMERIC(15,2) GENERATED ALWAYS AS (closing_balance - opening_balance) STORED,
+    total_deposits NUMERIC(15,2) DEFAULT 0.00,
+    total_withdrawals NUMERIC(15,2) DEFAULT 0.00,
+    average_daily_balance NUMERIC(15,2),
+    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
+    CONSTRAINT unique_account_month UNIQUE (account_id, month_year)
+);
+CREATE INDEX idx_monthly_balances_account ON monthly_balances(account_id);
+CREATE INDEX idx_monthly_balances_month ON monthly_balances(month_year);
+
+-- spending_patterns
+CREATE TABLE spending_patterns (
+    id SERIAL PRIMARY KEY,
+    category_id INTEGER REFERENCES categories(id),
+    account_id INTEGER REFERENCES accounts(id),
+    month_year DATE NOT NULL,
+    pattern_type VARCHAR(50) NOT NULL,
+    average_amount NUMERIC(15,2),
+    frequency_count INTEGER,
+    confidence_score NUMERIC(3,2),
+    pattern_data JSONB,
+    insights TEXT,
+    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
+    CONSTRAINT spending_patterns_pattern_type_check
+        CHECK (pattern_type IN ('weekly', 'monthly', 'seasonal', 'trending_up', 'trending_down', 'volatile', 'stable')),
+    CONSTRAINT spending_patterns_confidence_score_check CHECK (confidence_score >= 0.00 AND confidence_score <= 1.00)
+);
+CREATE INDEX idx_spending_patterns_category ON spending_patterns(category_id);
+CREATE INDEX idx_spending_patterns_month ON spending_patterns(month_year);
+CREATE INDEX idx_spending_patterns_type ON spending_patterns(pattern_type);
+
+-- financial_rules
+CREATE TABLE financial_rules (
+    id SERIAL PRIMARY KEY,
+    rule_name VARCHAR(200) NOT NULL,
+    rule_type VARCHAR(50) NOT NULL,
+    parameters JSONB NOT NULL,
+    conditions JSONB,
+    is_active BOOLEAN NOT NULL DEFAULT true,
+    priority INTEGER DEFAULT 5,
+    description TEXT,
+    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
+    CONSTRAINT financial_rules_rule_type_check
+        CHECK (rule_type IN ('budget_alert', 'spending_limit', 'savings_target', 'investment_allocation', 'debt_warning', 'cash_flow')),
+    CONSTRAINT financial_rules_priority_check CHECK (priority >= 1 AND priority <= 10)
+);
+CREATE INDEX idx_financial_rules_active ON financial_rules(is_active);
+CREATE INDEX idx_financial_rules_type ON financial_rules(rule_type);
+
+-- =============================================================================
+-- 3. VIEWS (8)
+-- =============================================================================
+
+CREATE VIEW v_transaction_details AS
+SELECT
+    t.id AS transaction_id,
+    t.transaction_date,
+    t.description AS transaction_description,
+    t.transaction_type,
+    t.total_amount,
+    te.id AS entry_id,
+    a.name AS account_name,
+    a.institution,
+    c.name AS category_name,
+    pc.name AS parent_category_name,
+    te.amount AS entry_amount,
+    te.entry_type,
+    te.description AS entry_description,
+    t.notes,
+    t.created_at
+FROM transactions t
+JOIN transaction_entries te ON t.id = te.transaction_id
+JOIN accounts a ON te.account_id = a.id
+LEFT JOIN categories c ON te.category_id = c.id
+LEFT JOIN categories pc ON c.parent_category_id = pc.id
+ORDER BY t.transaction_date DESC, t.id DESC, te.id;
+
+CREATE VIEW v_monthly_spending AS
+SELECT
+    date_trunc('month', t.transaction_date::timestamp with time zone) AS month_year,
+    c.name AS category,
+    c.category_type,
+    SUM(te.amount) AS total_amount,
+    COUNT(*) AS transaction_count,
+    AVG(te.amount) AS average_amount
+FROM transactions t
+JOIN transaction_entries te ON t.id = te.transaction_id
+LEFT JOIN categories c ON te.category_id = c.id
+WHERE t.transaction_type = 'expense'
+GROUP BY date_trunc('month', t.transaction_date::timestamp with time zone), c.name, c.category_type
+ORDER BY date_trunc('month', t.transaction_date::timestamp with time zone) DESC, SUM(te.amount) DESC;
+
+CREATE VIEW v_account_summary AS
+SELECT
+    a.id,
+    a.name,
+    at.name AS account_type,
+    a.current_balance,
+    a.currency,
+    a.is_active,
+    COALESCE(mb.closing_balance, a.current_balance) AS last_month_balance,
+    a.current_balance - COALESCE(mb.closing_balance, a.current_balance) AS monthly_change
+FROM accounts a
+LEFT JOIN account_types at ON a.account_type_id = at.id
+LEFT JOIN monthly_balances mb ON a.id = mb.account_id
+    AND mb.month_year = date_trunc('month', CURRENT_DATE - INTERVAL '1 month')
+WHERE a.is_active = true;
+
+CREATE VIEW v_category_hierarchy AS
+WITH RECURSIVE category_path AS (
+    SELECT id, name, parent_category_id, category_type,
+           name::text AS full_path, 1 AS level
+    FROM categories
+    WHERE parent_category_id IS NULL
+    UNION ALL
+    SELECT c.id, c.name, c.parent_category_id, c.category_type,
+           (cp.full_path || ' > ' || c.name::text) AS full_path,
+           cp.level + 1
+    FROM categories c
+    JOIN category_path cp ON c.parent_category_id = cp.id
+)
+SELECT id, name, parent_category_id, category_type, full_path, level
+FROM category_path;
+
+CREATE VIEW v_credit_utilization AS
+SELECT
+    id, name, current_balance, credit_limit,
+    ABS(current_balance) AS debt_owed,
+    credit_limit - ABS(current_balance) AS available_credit,
+    CASE WHEN credit_limit > 0
+         THEN ROUND(ABS(current_balance) / credit_limit * 100, 2)
+         ELSE 0
+    END AS utilization_percentage
+FROM accounts a
+WHERE account_type_id = (SELECT id FROM account_types WHERE name = 'Credit Card')
+  AND is_active = true;
+
+CREATE VIEW v_goal_progress_summary AS
+SELECT
+    g.id, g.name, g.description, g.goal_type, g.target_amount, g.current_amount,
+    g.target_date, g.priority, g.is_active, g.completion_percentage,
+    COALESCE(SUM(gc.planned_amount), 0) AS total_planned_contributions,
+    COALESCE(SUM(gc.actual_amount), 0) AS total_actual_contributions,
+    g.target_amount - g.current_amount AS amount_remaining,
+    CASE WHEN g.target_date IS NOT NULL
+         THEN EXTRACT(MONTH FROM AGE(g.target_date, CURRENT_DATE))
+         ELSE NULL
+    END AS months_remaining,
+    CASE WHEN g.target_date IS NOT NULL
+              AND EXTRACT(MONTH FROM AGE(g.target_date, CURRENT_DATE)) > 0
+         THEN ROUND((g.target_amount - g.current_amount) /
+              EXTRACT(MONTH FROM AGE(g.target_date, CURRENT_DATE)), 2)
+         ELSE NULL
+    END AS required_monthly_contribution
+FROM budget_goals g
+LEFT JOIN goal_contributions gc ON g.id = gc.goal_id
+GROUP BY g.id, g.name, g.description, g.goal_type, g.target_amount,
+         g.current_amount, g.target_date, g.priority, g.is_active, g.completion_percentage;
+
+CREATE VIEW v_monthly_contribution_summary AS
+SELECT
+    gc.month_year,
+    g.name AS goal_name,
+    g.goal_type,
+    gc.planned_amount,
+    gc.actual_amount,
+    gc.actual_amount - gc.planned_amount AS variance,
+    CASE WHEN gc.planned_amount > 0
+         THEN ROUND(gc.actual_amount / gc.planned_amount * 100, 2)
+         ELSE 0
+    END AS completion_percentage,
+    a.name AS source_account_name,
+    at.name AS source_account_type,
+    gc.notes,
+    gc.created_at
+FROM goal_contributions gc
+JOIN budget_goals g ON gc.goal_id = g.id
+LEFT JOIN accounts a ON gc.source_account_id = a.id
+LEFT JOIN account_types at ON a.account_type_id = at.id
+ORDER BY gc.month_year DESC, g.name;
+
+-- =============================================================================
+-- 4. SEED DATA
+-- =============================================================================
+
+-- 4a. Account Types (6 rows)
+INSERT INTO account_types (id, name, description) VALUES
+(1, 'Bank Account',    'Standard checking and business accounts'),
+(2, 'Investment',      'Investment accounts and portfolios'),
+(3, 'Credit Card',     'Credit card accounts'),
+(4, 'Cash',            'Physical cash on hand'),
+(5, 'Loan',            'Loan accounts'),
+(6, 'Savings Account', 'High-yield savings accounts');
+SELECT setval('account_types_id_seq', 6);
+
+-- 4b. Categories (35 rows with hierarchy)
+-- Parent expense categories
+INSERT INTO categories (id, name, parent_category_id, category_type, description) VALUES
+( 1, 'Housing',          NULL, 'expense', 'Housing and rent expenses'),
+( 2, 'Food & Dining',    NULL, 'expense', 'Groceries and restaurants'),
+( 3, 'Transportation',   NULL, 'expense', 'Getting around'),
+( 4, 'Business',         NULL, 'expense', 'Business operating expenses'),
+( 5, 'Health & Fitness', NULL, 'expense', 'Health insurance and fitness'),
+( 6, 'Entertainment',    NULL, 'expense', 'Fun and leisure'),
+( 7, 'Subscriptions',    NULL, 'expense', 'Recurring subscriptions'),
+( 8, 'Utilities',        NULL, 'expense', 'Utility bills'),
+( 9, 'Personal Care',    NULL, 'expense', 'Personal care and grooming'),
+(10, 'Education',        NULL, 'expense', 'Learning and courses');
+
+-- Child expense categories
+INSERT INTO categories (id, name, parent_category_id, category_type, description) VALUES
+(11, 'Rent',                  1, 'expense', 'Monthly rent payment'),
+(12, 'Groceries',             2, 'expense', 'Grocery shopping'),
+(13, 'Dining Out',            2, 'expense', 'Restaurants and takeout'),
+(14, 'Coffee Shops',          2, 'expense', 'Coffee and cafe visits'),
+(15, 'Uber/Lyft',             3, 'expense', 'Rideshare services'),
+(16, 'Gas',                   3, 'expense', 'Fuel for car'),
+(17, 'Software Subscriptions', 4, 'expense', 'SaaS tools for work'),
+(18, 'Coworking',             4, 'expense', 'Coworking space membership'),
+(19, 'Equipment',             4, 'expense', 'Hardware and office equipment'),
+(20, 'Contractors',           4, 'expense', 'Subcontractor payments'),
+(21, 'Marketing',             4, 'expense', 'Advertising and promotion'),
+(22, 'Legal & Accounting',    4, 'expense', 'Professional services'),
+(23, 'Health Insurance',      5, 'expense', 'Monthly health insurance premium'),
+(24, 'Gym',                   5, 'expense', 'Gym membership'),
+(25, 'Streaming',             7, 'expense', 'Netflix, Spotify, etc.'),
+(26, 'Cloud Services',        7, 'expense', 'AWS, hosting, domains'),
+(27, 'Internet',              8, 'expense', 'Home internet service'),
+(28, 'Phone',                 8, 'expense', 'Mobile phone plan'),
+(29, 'Electricity',           8, 'expense', 'Electric bill');
+
+-- Income categories
+INSERT INTO categories (id, name, parent_category_id, category_type, description) VALUES
+(30, 'Client Invoices',      NULL, 'income', 'One-time client project payments'),
+(31, 'Recurring Retainers',  NULL, 'income', 'Monthly retainer clients'),
+(32, 'Affiliate Income',     NULL, 'income', 'Affiliate and referral commissions'),
+(33, 'Interest',             NULL, 'income', 'Interest earned on savings');
+
+-- Transfer categories
+INSERT INTO categories (id, name, parent_category_id, category_type, description) VALUES
+(34, 'Internal Transfer',    NULL, 'transfer', 'Transfers between own accounts'),
+(35, 'Credit Card Payment',  NULL, 'transfer', 'Paying off credit card balance');
+
+SELECT setval('categories_id_seq', 35);
+
+-- 4c. Accounts (11 rows)
+INSERT INTO accounts (id, name, account_type_id, current_balance, is_active, account_number, institution, currency, credit_limit, opening_balance) VALUES
+( 1, 'Chase Personal Checking', 1,     0.00, true, '****4521', 'Chase',    'USD', NULL,    8000.00),
+( 2, 'Chase Business Checking', 1,     0.00, true, '****8903', 'Chase',    'USD', NULL,    3000.00),
+( 3, 'PayPal',                  1,     0.00, true, NULL,       'PayPal',   'USD', NULL,       0.00),
+( 4, 'Stripe',                  1,     0.00, true, NULL,       'Stripe',   'USD', NULL,       0.00),
+( 5, 'Wise',                    1,     0.00, true, NULL,       'Wise',     'USD', NULL,       0.00),
+( 6, 'High-Yield Savings',      6,     0.00, true, '****7712', 'Marcus',   'USD', NULL,   10000.00),
+( 7, 'Cash',                    4,     0.00, true, NULL,        NULL,      'USD', NULL,     500.00),
+( 8, 'Chase Sapphire',          3,     0.00, true, '****3344', 'Chase',    'USD', 10000.00,  0.00),
+( 9, 'Amex Blue',               3,     0.00, true, '****2211', 'Amex',     'USD',  5000.00,  0.00),
+(10, 'Fidelity Brokerage',      2,     0.00, true, '****9988', 'Fidelity', 'USD', NULL,   20000.00),
+(11, 'Fidelity Roth IRA',       2,     0.00, true, '****5566', 'Fidelity', 'USD', NULL,    8000.00);
+SELECT setval('accounts_id_seq', 11);
+
+-- =============================================================================
+-- 4d. Transactions + Entries
+-- Covering Oct 2025 – Jan 2026 (4 months)
+-- =============================================================================
+
+-- Helper: We'll use explicit IDs for transactions so entries can reference them.
+
+-- ===================== OCTOBER 2025 =====================
+
+-- Income
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(1, '2025-10-03', 'Client: Riverside Marketing - Website Redesign', 'income', 5500.00),
+(2, '2025-10-10', 'Client: TechStart Inc - Monthly Retainer', 'income', 1500.00),
+(3, '2025-10-15', 'Client: GreenLeaf Co - E-commerce Store', 'income', 3200.00),
+(4, '2025-10-20', 'Client: DataFlow Systems - API Integration', 'income', 4000.00),
+(5, '2025-10-25', 'Client: BlueSky Media - Monthly Retainer', 'income', 1500.00);
+
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(1, 4, 30, 5500.00, 'credit', 'Stripe deposit - Riverside Marketing'),
+(2, 2, 31, 1500.00, 'credit', 'Direct deposit - TechStart retainer'),
+(3, 3, 30, 3200.00, 'credit', 'PayPal deposit - GreenLeaf Co'),
+(4, 4, 30, 4000.00, 'credit', 'Stripe deposit - DataFlow Systems'),
+(5, 2, 31, 1500.00, 'credit', 'Direct deposit - BlueSky retainer');
+
+-- Expenses - Housing & Utilities
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(6,  '2025-10-01', 'October Rent', 'expense', 1800.00),
+(7,  '2025-10-05', 'Internet - Comcast', 'expense', 79.99),
+(8,  '2025-10-08', 'Phone - T-Mobile', 'expense', 55.00),
+(9,  '2025-10-12', 'Electric Bill - ConEd', 'expense', 95.00);
+
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(6,  1, 11, 1800.00, 'debit', 'Rent payment'),
+(7,  1, 27, 79.99,   'debit', 'Internet service'),
+(8,  1, 28, 55.00,   'debit', 'Mobile plan'),
+(9,  1, 29, 95.00,   'debit', 'Electric bill');
+
+-- Expenses - Business
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(10, '2025-10-01', 'Figma - Pro Plan', 'expense', 15.00),
+(11, '2025-10-01', 'GitHub - Team Plan', 'expense', 25.00),
+(12, '2025-10-01', 'Vercel - Pro Hosting', 'expense', 20.00),
+(13, '2025-10-01', 'Google Workspace', 'expense', 12.00),
+(14, '2025-10-01', 'WeWork - Hot Desk', 'expense', 350.00),
+(15, '2025-10-15', 'Contractor: Sarah - Design Work', 'expense', 800.00),
+(16, '2025-10-20', 'AWS Monthly', 'expense', 45.50);
+
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(10, 9, 17, 15.00,   'debit', 'Figma subscription'),
+(11, 9, 17, 25.00,   'debit', 'GitHub subscription'),
+(12, 9, 17, 20.00,   'debit', 'Vercel hosting'),
+(13, 9, 17, 12.00,   'debit', 'Google Workspace'),
+(14, 2, 18, 350.00,  'debit', 'Coworking monthly'),
+(15, 2, 20, 800.00,  'debit', 'Sarah - UI design for Riverside'),
+(16, 9, 26, 45.50,   'debit', 'AWS hosting');
+
+-- Expenses - Food & Dining
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(17, '2025-10-02', 'Whole Foods', 'expense', 87.30),
+(18, '2025-10-06', 'Trader Joes', 'expense', 62.15),
+(19, '2025-10-09', 'Chipotle', 'expense', 14.50),
+(20, '2025-10-13', 'Whole Foods', 'expense', 95.20),
+(21, '2025-10-16', 'Thai Basil Restaurant', 'expense', 42.00),
+(22, '2025-10-18', 'Starbucks', 'expense', 6.75),
+(23, '2025-10-22', 'Trader Joes', 'expense', 58.40),
+(24, '2025-10-25', 'Shake Shack', 'expense', 18.90),
+(25, '2025-10-28', 'Whole Foods', 'expense', 78.60),
+(26, '2025-10-30', 'Blue Bottle Coffee', 'expense', 5.50);
+
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(17, 8, 12, 87.30,   'debit', 'Weekly groceries'),
+(18, 8, 12, 62.15,   'debit', 'Weekly groceries'),
+(19, 8, 13, 14.50,   'debit', 'Lunch'),
+(20, 8, 12, 95.20,   'debit', 'Weekly groceries'),
+(21, 8, 13, 42.00,   'debit', 'Dinner out'),
+(22, 7, 14, 6.75,    'debit', 'Morning coffee'),
+(23, 8, 12, 58.40,   'debit', 'Weekly groceries'),
+(24, 8, 13, 18.90,   'debit', 'Lunch out'),
+(25, 8, 12, 78.60,   'debit', 'Weekly groceries'),
+(26, 7, 14, 5.50,    'debit', 'Coffee');
+
+-- Expenses - Health & Entertainment
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(27, '2025-10-01', 'Blue Cross - Health Insurance', 'expense', 450.00),
+(28, '2025-10-01', 'Equinox Gym', 'expense', 95.00),
+(29, '2025-10-05', 'Netflix', 'expense', 15.49),
+(30, '2025-10-05', 'Spotify', 'expense', 10.99),
+(31, '2025-10-14', 'Movie Theater - AMC', 'expense', 22.00),
+(32, '2025-10-22', 'Concert Tickets - MSG', 'expense', 120.00);
+
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(27, 1, 23, 450.00,  'debit', 'Monthly health premium'),
+(28, 1, 24, 95.00,   'debit', 'Gym membership'),
+(29, 1, 25, 15.49,   'debit', 'Netflix subscription'),
+(30, 1, 25, 10.99,   'debit', 'Spotify subscription'),
+(31, 8, 6,  22.00,   'debit', 'Movie tickets'),
+(32, 8, 6,  120.00,  'debit', 'Concert');
+
+-- Expenses - Transportation
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(33, '2025-10-07', 'Uber to client meeting', 'expense', 28.50),
+(34, '2025-10-19', 'Lyft to airport', 'expense', 45.00);
+
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(33, 8, 15, 28.50,   'debit', 'Uber ride'),
+(34, 8, 15, 45.00,   'debit', 'Lyft ride');
+
+-- Transfers - October
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(35, '2025-10-05', 'Transfer to savings', 'transfer', 1000.00),
+(36, '2025-10-15', 'Investment contribution', 'transfer', 500.00),
+(37, '2025-10-15', 'Roth IRA contribution', 'transfer', 500.00),
+(38, '2025-10-28', 'Chase Sapphire payment', 'transfer', 500.00),
+(39, '2025-10-10', 'PayPal to Business Checking', 'transfer', 3200.00);
+
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(35, 1, NULL, 1000.00, 'debit',  'To savings'),
+(35, 6, NULL, 1000.00, 'credit', 'From checking'),
+(36, 1, NULL, 500.00,  'debit',  'To brokerage'),
+(36, 10, NULL, 500.00, 'credit', 'Monthly investment'),
+(37, 1, NULL, 500.00,  'debit',  'To Roth IRA'),
+(37, 11, NULL, 500.00, 'credit', 'Monthly Roth contribution'),
+(38, 1, NULL, 500.00,  'debit',  'CC payment'),
+(38, 8, NULL, 500.00,  'credit', 'Payment received'),
+(39, 3, NULL, 3200.00, 'debit',  'Withdraw to bank'),
+(39, 2, NULL, 3200.00, 'credit', 'From PayPal');
+
+-- Monthly transfer: business to personal for living expenses
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(200, '2025-10-02', 'Transfer from Business to Personal', 'transfer', 5000.00);
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(200, 2, NULL, 5000.00, 'debit',  'To personal checking'),
+(200, 1, NULL, 5000.00, 'credit', 'From business checking');
+
+-- ===================== NOVEMBER 2025 =====================
+
+-- Income
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(40, '2025-11-05', 'Client: TechStart Inc - Monthly Retainer', 'income', 1500.00),
+(41, '2025-11-07', 'Client: Artisan Bakery - New Website', 'income', 2800.00),
+(42, '2025-11-12', 'Client: DataFlow Systems - Phase 2', 'income', 6000.00),
+(43, '2025-11-20', 'Client: BlueSky Media - Monthly Retainer', 'income', 1500.00),
+(44, '2025-11-25', 'Affiliate Commission - WPEngine', 'income', 350.00),
+(45, '2025-11-28', 'Client: Peak Performance - Landing Page', 'income', 1800.00);
+
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(40, 2,  31, 1500.00, 'credit', 'Direct deposit - TechStart retainer'),
+(41, 3,  30, 2800.00, 'credit', 'PayPal deposit - Artisan Bakery'),
+(42, 4,  30, 6000.00, 'credit', 'Stripe deposit - DataFlow Systems'),
+(43, 2,  31, 1500.00, 'credit', 'Direct deposit - BlueSky retainer'),
+(44, 3,  32, 350.00,  'credit', 'WPEngine affiliate payout'),
+(45, 5,  30, 1800.00, 'credit', 'Wise deposit - Peak Performance (UK client)');
+
+-- Expenses - Housing & Utilities (Nov)
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(46, '2025-11-01', 'November Rent', 'expense', 1800.00),
+(47, '2025-11-05', 'Internet - Comcast', 'expense', 79.99),
+(48, '2025-11-08', 'Phone - T-Mobile', 'expense', 55.00),
+(49, '2025-11-15', 'Electric Bill - ConEd', 'expense', 110.00);
+
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(46, 1, 11, 1800.00, 'debit', 'Rent payment'),
+(47, 1, 27, 79.99,   'debit', 'Internet service'),
+(48, 1, 28, 55.00,   'debit', 'Mobile plan'),
+(49, 1, 29, 110.00,  'debit', 'Electric bill');
+
+-- Expenses - Business (Nov)
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(50, '2025-11-01', 'Figma - Pro Plan', 'expense', 15.00),
+(51, '2025-11-01', 'GitHub - Team Plan', 'expense', 25.00),
+(52, '2025-11-01', 'Vercel - Pro Hosting', 'expense', 20.00),
+(53, '2025-11-01', 'Google Workspace', 'expense', 12.00),
+(54, '2025-11-01', 'WeWork - Hot Desk', 'expense', 350.00),
+(55, '2025-11-10', 'Contractor: Mike - Backend Dev', 'expense', 1200.00),
+(56, '2025-11-18', 'AWS Monthly', 'expense', 52.30),
+(57, '2025-11-20', 'Adobe Creative Cloud', 'expense', 54.99),
+(58, '2025-11-22', 'Notion - Team Plan', 'expense', 10.00);
+
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(50, 9,  17, 15.00,   'debit', 'Figma subscription'),
+(51, 9,  17, 25.00,   'debit', 'GitHub subscription'),
+(52, 9,  17, 20.00,   'debit', 'Vercel hosting'),
+(53, 9,  17, 12.00,   'debit', 'Google Workspace'),
+(54, 2,  18, 350.00,  'debit', 'Coworking monthly'),
+(55, 2,  20, 1200.00, 'debit', 'Mike - backend for DataFlow'),
+(56, 9,  26, 52.30,   'debit', 'AWS hosting'),
+(57, 9,  17, 54.99,   'debit', 'Adobe CC'),
+(58, 9,  17, 10.00,   'debit', 'Notion subscription');
+
+-- Expenses - Food & Dining (Nov)
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(59, '2025-11-02', 'Whole Foods', 'expense', 92.40),
+(60, '2025-11-06', 'Trader Joes', 'expense', 55.80),
+(61, '2025-11-09', 'Sushi Nakazawa', 'expense', 85.00),
+(62, '2025-11-13', 'Whole Foods', 'expense', 88.10),
+(63, '2025-11-17', 'Panda Express', 'expense', 12.50),
+(64, '2025-11-19', 'Starbucks', 'expense', 7.25),
+(65, '2025-11-23', 'Trader Joes', 'expense', 67.30),
+(66, '2025-11-26', 'Thanksgiving Groceries - Whole Foods', 'expense', 145.00),
+(67, '2025-11-28', 'Blue Bottle Coffee', 'expense', 5.50),
+(68, '2025-11-30', 'Sweetgreen', 'expense', 16.50);
+
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(59, 8,  12, 92.40,   'debit', 'Weekly groceries'),
+(60, 8,  12, 55.80,   'debit', 'Weekly groceries'),
+(61, 8,  13, 85.00,   'debit', 'Dinner out'),
+(62, 8,  12, 88.10,   'debit', 'Weekly groceries'),
+(63, 8,  13, 12.50,   'debit', 'Lunch'),
+(64, 7,  14, 7.25,    'debit', 'Morning coffee'),
+(65, 8,  12, 67.30,   'debit', 'Weekly groceries'),
+(66, 8,  12, 145.00,  'debit', 'Thanksgiving groceries'),
+(67, 7,  14, 5.50,    'debit', 'Coffee'),
+(68, 8,  13, 16.50,   'debit', 'Lunch');
+
+-- Expenses - Health & Entertainment (Nov)
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(69, '2025-11-01', 'Blue Cross - Health Insurance', 'expense', 450.00),
+(70, '2025-11-01', 'Equinox Gym', 'expense', 95.00),
+(71, '2025-11-05', 'Netflix', 'expense', 15.49),
+(72, '2025-11-05', 'Spotify', 'expense', 10.99),
+(73, '2025-11-15', 'Broadway Show', 'expense', 150.00),
+(74, '2025-11-22', 'Video Game - Steam', 'expense', 39.99);
+
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(69, 1, 23, 450.00,  'debit', 'Monthly health premium'),
+(70, 1, 24, 95.00,   'debit', 'Gym membership'),
+(71, 1, 25, 15.49,   'debit', 'Netflix subscription'),
+(72, 1, 25, 10.99,   'debit', 'Spotify subscription'),
+(73, 8, 6,  150.00,  'debit', 'Broadway tickets'),
+(74, 1, 6,  39.99,   'debit', 'Steam purchase');
+
+-- Expenses - Transportation (Nov)
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(75, '2025-11-03', 'Uber to coworking', 'expense', 15.00),
+(76, '2025-11-14', 'Lyft to client dinner', 'expense', 22.50);
+
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(75, 8, 15, 15.00,   'debit', 'Uber ride'),
+(76, 8, 15, 22.50,   'debit', 'Lyft ride');
+
+-- Transfers - November
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(77, '2025-11-05', 'Transfer to savings', 'transfer', 1500.00),
+(78, '2025-11-15', 'Investment contribution', 'transfer', 500.00),
+(79, '2025-11-15', 'Roth IRA contribution', 'transfer', 500.00),
+(80, '2025-11-25', 'Amex Blue payment', 'transfer', 300.00),
+(81, '2025-11-08', 'Stripe to Business Checking', 'transfer', 6000.00),
+(82, '2025-11-26', 'Wise to Business Checking', 'transfer', 1800.00);
+
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(77, 1, NULL,  1500.00, 'debit',  'To savings'),
+(77, 6, NULL,  1500.00, 'credit', 'From checking'),
+(78, 1, NULL,  500.00,  'debit',  'To brokerage'),
+(78, 10, NULL, 500.00,  'credit', 'Monthly investment'),
+(79, 1, NULL,  500.00,  'debit',  'To Roth IRA'),
+(79, 11, NULL, 500.00,  'credit', 'Monthly Roth contribution'),
+(80, 2, NULL,  300.00,  'debit',  'CC payment'),
+(80, 9, NULL,  300.00,  'credit', 'Payment received'),
+(81, 4, NULL,  6000.00, 'debit',  'Withdraw to bank'),
+(81, 2, NULL,  6000.00, 'credit', 'From Stripe'),
+(82, 5, NULL,  1800.00, 'debit',  'Withdraw to bank'),
+(82, 2, NULL,  1800.00, 'credit', 'From Wise');
+
+-- Monthly transfer: business to personal for living expenses
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(201, '2025-11-02', 'Transfer from Business to Personal', 'transfer', 5000.00);
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(201, 2, NULL, 5000.00, 'debit',  'To personal checking'),
+(201, 1, NULL, 5000.00, 'credit', 'From business checking');
+
+-- ===================== DECEMBER 2025 =====================
+
+-- Income
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(83,  '2025-12-03', 'Client: TechStart Inc - Monthly Retainer', 'income', 1500.00),
+(84,  '2025-12-05', 'Client: Riverside Marketing - Phase 2 Maintenance', 'income', 2000.00),
+(85,  '2025-12-10', 'Client: MindfulApps - Mobile App Design', 'income', 7500.00),
+(86,  '2025-12-18', 'Client: BlueSky Media - Monthly Retainer', 'income', 1500.00),
+(87,  '2025-12-22', 'Client: GreenLeaf Co - Holiday Campaign', 'income', 3000.00),
+(88,  '2025-12-28', 'Interest - Marcus Savings', 'income', 52.30);
+
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(83,  2, 31, 1500.00, 'credit', 'Direct deposit - TechStart retainer'),
+(84,  4, 30, 2000.00, 'credit', 'Stripe deposit - Riverside maintenance'),
+(85,  4, 30, 7500.00, 'credit', 'Stripe deposit - MindfulApps'),
+(86,  2, 31, 1500.00, 'credit', 'Direct deposit - BlueSky retainer'),
+(87,  3, 30, 3000.00, 'credit', 'PayPal deposit - GreenLeaf Co'),
+(88,  6, 33, 52.30,   'credit', 'Monthly interest');
+
+-- Expenses - Housing & Utilities (Dec)
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(89,  '2025-12-01', 'December Rent', 'expense', 1800.00),
+(90,  '2025-12-05', 'Internet - Comcast', 'expense', 79.99),
+(91,  '2025-12-08', 'Phone - T-Mobile', 'expense', 55.00),
+(92,  '2025-12-18', 'Electric Bill - ConEd', 'expense', 125.00);
+
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(89,  1, 11, 1800.00, 'debit', 'Rent payment'),
+(90,  1, 27, 79.99,   'debit', 'Internet service'),
+(91,  1, 28, 55.00,   'debit', 'Mobile plan'),
+(92,  1, 29, 125.00,  'debit', 'Electric bill - winter');
+
+-- Expenses - Business (Dec)
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(93,  '2025-12-01', 'Figma - Pro Plan', 'expense', 15.00),
+(94,  '2025-12-01', 'GitHub - Team Plan', 'expense', 25.00),
+(95,  '2025-12-01', 'Vercel - Pro Hosting', 'expense', 20.00),
+(96,  '2025-12-01', 'Google Workspace', 'expense', 12.00),
+(97,  '2025-12-01', 'WeWork - Hot Desk', 'expense', 350.00),
+(98,  '2025-12-08', 'Contractor: Sarah - Design Work', 'expense', 600.00),
+(99,  '2025-12-15', 'Contractor: Mike - Backend Dev', 'expense', 1500.00),
+(100, '2025-12-20', 'AWS Monthly', 'expense', 58.70),
+(101, '2025-12-01', 'Adobe Creative Cloud', 'expense', 54.99),
+(102, '2025-12-01', 'Notion - Team Plan', 'expense', 10.00),
+(103, '2025-12-10', 'Business lunch with client', 'expense', 85.00);
+
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(93,  9, 17, 15.00,   'debit', 'Figma subscription'),
+(94,  9, 17, 25.00,   'debit', 'GitHub subscription'),
+(95,  9, 17, 20.00,   'debit', 'Vercel hosting'),
+(96,  9, 17, 12.00,   'debit', 'Google Workspace'),
+(97,  2, 18, 350.00,  'debit', 'Coworking monthly'),
+(98,  2, 20, 600.00,  'debit', 'Sarah - design for MindfulApps'),
+(99,  2, 20, 1500.00, 'debit', 'Mike - backend for MindfulApps'),
+(100, 9, 26, 58.70,   'debit', 'AWS hosting'),
+(101, 9, 17, 54.99,   'debit', 'Adobe CC'),
+(102, 9, 17, 10.00,   'debit', 'Notion subscription'),
+(103, 9, 13, 85.00,   'debit', 'Client lunch');
+
+-- Expenses - Food & Dining (Dec)
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(104, '2025-12-01', 'Whole Foods', 'expense', 105.20),
+(105, '2025-12-05', 'Trader Joes', 'expense', 72.40),
+(106, '2025-12-08', 'Italian Restaurant', 'expense', 65.00),
+(107, '2025-12-12', 'Whole Foods', 'expense', 98.30),
+(108, '2025-12-15', 'Starbucks', 'expense', 7.25),
+(109, '2025-12-18', 'Holiday dinner - Nobu', 'expense', 180.00),
+(110, '2025-12-22', 'Trader Joes', 'expense', 85.60),
+(111, '2025-12-24', 'Christmas groceries - Whole Foods', 'expense', 165.00),
+(112, '2025-12-27', 'Blue Bottle Coffee', 'expense', 5.50),
+(113, '2025-12-29', 'Sweetgreen', 'expense', 16.50);
+
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(104, 8, 12, 105.20, 'debit', 'Weekly groceries'),
+(105, 8, 12, 72.40,  'debit', 'Weekly groceries'),
+(106, 8, 13, 65.00,  'debit', 'Dinner out'),
+(107, 8, 12, 98.30,  'debit', 'Weekly groceries'),
+(108, 7, 14, 7.25,   'debit', 'Morning coffee'),
+(109, 8, 13, 180.00, 'debit', 'Holiday dinner'),
+(110, 8, 12, 85.60,  'debit', 'Weekly groceries'),
+(111, 8, 12, 165.00, 'debit', 'Christmas groceries'),
+(112, 7, 14, 5.50,   'debit', 'Coffee'),
+(113, 8, 13, 16.50,  'debit', 'Lunch');
+
+-- Expenses - Health & Entertainment (Dec)
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(114, '2025-12-01', 'Blue Cross - Health Insurance', 'expense', 450.00),
+(115, '2025-12-01', 'Equinox Gym', 'expense', 95.00),
+(116, '2025-12-05', 'Netflix', 'expense', 15.49),
+(117, '2025-12-05', 'Spotify', 'expense', 10.99),
+(118, '2025-12-12', 'Holiday party supplies', 'expense', 75.00),
+(119, '2025-12-20', 'Christmas gifts', 'expense', 350.00);
+
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(114, 1, 23, 450.00, 'debit', 'Monthly health premium'),
+(115, 1, 24, 95.00,  'debit', 'Gym membership'),
+(116, 1, 25, 15.49,  'debit', 'Netflix subscription'),
+(117, 1, 25, 10.99,  'debit', 'Spotify subscription'),
+(118, 8, 6,  75.00,  'debit', 'Party supplies'),
+(119, 8, 6,  350.00, 'debit', 'Christmas gifts');
+
+-- Expenses - Transportation (Dec)
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(120, '2025-12-04', 'Uber to client meeting', 'expense', 32.00),
+(121, '2025-12-15', 'Lyft to holiday party', 'expense', 18.50);
+
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(120, 8, 15, 32.00,  'debit', 'Uber ride'),
+(121, 8, 15, 18.50,  'debit', 'Lyft ride');
+
+-- Transfers - December
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(122, '2025-12-05', 'Transfer to savings', 'transfer', 2000.00),
+(123, '2025-12-15', 'Investment contribution', 'transfer', 1000.00),
+(124, '2025-12-15', 'Roth IRA contribution', 'transfer', 500.00),
+(125, '2025-12-28', 'Chase Sapphire payment', 'transfer', 800.00),
+(126, '2025-12-28', 'Amex Blue payment', 'transfer', 400.00),
+(127, '2025-12-06', 'Stripe to Business Checking', 'transfer', 9500.00),
+(128, '2025-12-08', 'PayPal to Business Checking', 'transfer', 3000.00);
+
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(122, 1,  NULL, 2000.00,  'debit',  'To savings'),
+(122, 6,  NULL, 2000.00,  'credit', 'From checking'),
+(123, 1,  NULL, 1000.00,  'debit',  'To brokerage'),
+(123, 10, NULL, 1000.00,  'credit', 'Monthly investment - extra'),
+(124, 1,  NULL, 500.00,   'debit',  'To Roth IRA'),
+(124, 11, NULL, 500.00,   'credit', 'Monthly Roth contribution'),
+(125, 1,  NULL, 800.00,   'debit',  'CC payment'),
+(125, 8,  NULL, 800.00,   'credit', 'Payment received'),
+(126, 2,  NULL, 400.00,   'debit',  'CC payment'),
+(126, 9,  NULL, 400.00,   'credit', 'Payment received'),
+(127, 4,  NULL, 9500.00,  'debit',  'Withdraw to bank'),
+(127, 2,  NULL, 9500.00,  'credit', 'From Stripe'),
+(128, 3,  NULL, 3000.00,  'debit',  'Withdraw to bank'),
+(128, 2,  NULL, 3000.00,  'credit', 'From PayPal');
+
+-- Monthly transfer: business to personal for living expenses
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(202, '2025-12-02', 'Transfer from Business to Personal', 'transfer', 5500.00);
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(202, 2, NULL, 5500.00, 'debit',  'To personal checking'),
+(202, 1, NULL, 5500.00, 'credit', 'From business checking');
+
+-- ===================== JANUARY 2026 =====================
+
+-- Income
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(129, '2026-01-05', 'Client: TechStart Inc - Monthly Retainer', 'income', 1500.00),
+(130, '2026-01-08', 'Client: MindfulApps - Phase 2', 'income', 4500.00),
+(131, '2026-01-12', 'Client: Summit Analytics - Dashboard', 'income', 5000.00),
+(132, '2026-01-20', 'Client: BlueSky Media - Monthly Retainer', 'income', 1500.00),
+(133, '2026-01-22', 'Client: Peak Performance - Phase 2', 'income', 2500.00),
+(134, '2026-01-28', 'Affiliate Commission - WPEngine', 'income', 280.00),
+(135, '2026-01-30', 'Interest - Marcus Savings', 'income', 58.75);
+
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(129, 2, 31, 1500.00, 'credit', 'Direct deposit - TechStart retainer'),
+(130, 4, 30, 4500.00, 'credit', 'Stripe deposit - MindfulApps'),
+(131, 4, 30, 5000.00, 'credit', 'Stripe deposit - Summit Analytics'),
+(132, 2, 31, 1500.00, 'credit', 'Direct deposit - BlueSky retainer'),
+(133, 5, 30, 2500.00, 'credit', 'Wise deposit - Peak Performance (UK)'),
+(134, 3, 32, 280.00,  'credit', 'WPEngine affiliate payout'),
+(135, 6, 33, 58.75,   'credit', 'Monthly interest');
+
+-- Expenses - Housing & Utilities (Jan)
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(136, '2026-01-01', 'January Rent', 'expense', 1800.00),
+(137, '2026-01-05', 'Internet - Comcast', 'expense', 79.99),
+(138, '2026-01-08', 'Phone - T-Mobile', 'expense', 55.00),
+(139, '2026-01-20', 'Electric Bill - ConEd', 'expense', 140.00);
+
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(136, 1, 11, 1800.00, 'debit', 'Rent payment'),
+(137, 1, 27, 79.99,   'debit', 'Internet service'),
+(138, 1, 28, 55.00,   'debit', 'Mobile plan'),
+(139, 1, 29, 140.00,  'debit', 'Electric bill - winter peak');
+
+-- Expenses - Business (Jan)
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(140, '2026-01-01', 'Figma - Pro Plan', 'expense', 15.00),
+(141, '2026-01-01', 'GitHub - Team Plan', 'expense', 25.00),
+(142, '2026-01-01', 'Vercel - Pro Hosting', 'expense', 20.00),
+(143, '2026-01-01', 'Google Workspace', 'expense', 12.00),
+(144, '2026-01-01', 'WeWork - Hot Desk', 'expense', 350.00),
+(145, '2026-01-10', 'Contractor: Sarah - Design Work', 'expense', 900.00),
+(146, '2026-01-18', 'AWS Monthly', 'expense', 61.20),
+(147, '2026-01-01', 'Adobe Creative Cloud', 'expense', 54.99),
+(148, '2026-01-01', 'Notion - Team Plan', 'expense', 10.00),
+(149, '2026-01-15', 'New monitor - Dell Ultrawide', 'expense', 650.00),
+(150, '2026-01-08', 'Online course - Advanced React Patterns', 'expense', 49.00);
+
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(140, 9,  17, 15.00,   'debit', 'Figma subscription'),
+(141, 9,  17, 25.00,   'debit', 'GitHub subscription'),
+(142, 9,  17, 20.00,   'debit', 'Vercel hosting'),
+(143, 9,  17, 12.00,   'debit', 'Google Workspace'),
+(144, 2,  18, 350.00,  'debit', 'Coworking monthly'),
+(145, 2,  20, 900.00,  'debit', 'Sarah - design for Summit'),
+(146, 9,  26, 61.20,   'debit', 'AWS hosting'),
+(147, 9,  17, 54.99,   'debit', 'Adobe CC'),
+(148, 9,  17, 10.00,   'debit', 'Notion subscription'),
+(149, 9,  19, 650.00,  'debit', 'Dell monitor'),
+(150, 9,  10, 49.00,   'debit', 'React course');
+
+-- Expenses - Food & Dining (Jan)
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(151, '2026-01-03', 'Whole Foods', 'expense', 88.90),
+(152, '2026-01-07', 'Trader Joes', 'expense', 64.20),
+(153, '2026-01-10', 'Ramen Bar', 'expense', 22.00),
+(154, '2026-01-14', 'Whole Foods', 'expense', 91.50),
+(155, '2026-01-17', 'Starbucks', 'expense', 6.75),
+(156, '2026-01-19', 'Dim Sum Palace', 'expense', 55.00),
+(157, '2026-01-23', 'Trader Joes', 'expense', 59.80),
+(158, '2026-01-26', 'Sweetgreen', 'expense', 16.50),
+(159, '2026-01-28', 'Whole Foods', 'expense', 82.40),
+(160, '2026-01-30', 'Blue Bottle Coffee', 'expense', 5.50);
+
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(151, 8,  12, 88.90,  'debit', 'Weekly groceries'),
+(152, 8,  12, 64.20,  'debit', 'Weekly groceries'),
+(153, 8,  13, 22.00,  'debit', 'Lunch out'),
+(154, 8,  12, 91.50,  'debit', 'Weekly groceries'),
+(155, 7,  14, 6.75,   'debit', 'Morning coffee'),
+(156, 8,  13, 55.00,  'debit', 'Dinner out'),
+(157, 8,  12, 59.80,  'debit', 'Weekly groceries'),
+(158, 8,  13, 16.50,  'debit', 'Lunch'),
+(159, 8,  12, 82.40,  'debit', 'Weekly groceries'),
+(160, 7,  14, 5.50,   'debit', 'Coffee');
+
+-- Expenses - Health & Entertainment (Jan)
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(161, '2026-01-01', 'Blue Cross - Health Insurance', 'expense', 450.00),
+(162, '2026-01-01', 'Equinox Gym', 'expense', 95.00),
+(163, '2026-01-05', 'Netflix', 'expense', 15.49),
+(164, '2026-01-05', 'Spotify', 'expense', 10.99),
+(165, '2026-01-18', 'Escape Room', 'expense', 40.00),
+(166, '2026-01-25', 'Comedy Show', 'expense', 60.00);
+
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(161, 1, 23, 450.00,  'debit', 'Monthly health premium'),
+(162, 1, 24, 95.00,   'debit', 'Gym membership'),
+(163, 1, 25, 15.49,   'debit', 'Netflix subscription'),
+(164, 1, 25, 10.99,   'debit', 'Spotify subscription'),
+(165, 8, 6,  40.00,   'debit', 'Escape room'),
+(166, 8, 6,  60.00,   'debit', 'Comedy show');
+
+-- Expenses - Transportation (Jan)
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(167, '2026-01-06', 'Uber to coworking', 'expense', 18.00),
+(168, '2026-01-14', 'Uber to client meeting', 'expense', 25.50),
+(169, '2026-01-22', 'Lyft to airport', 'expense', 48.00);
+
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(167, 8, 15, 18.00,  'debit', 'Uber ride'),
+(168, 8, 15, 25.50,  'debit', 'Uber to client'),
+(169, 8, 15, 48.00,  'debit', 'Lyft to JFK');
+
+-- Transfers - January
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(170, '2026-01-05', 'Transfer to savings', 'transfer', 1500.00),
+(171, '2026-01-15', 'Investment contribution', 'transfer', 1000.00),
+(172, '2026-01-15', 'Roth IRA contribution', 'transfer', 500.00),
+(173, '2026-01-28', 'Chase Sapphire payment', 'transfer', 700.00),
+(174, '2026-01-28', 'Amex Blue payment', 'transfer', 500.00),
+(175, '2026-01-09', 'Stripe to Business Checking', 'transfer', 9500.00),
+(176, '2026-01-23', 'Wise to Business Checking', 'transfer', 2500.00),
+(177, '2026-01-12', 'PayPal to Personal Checking', 'transfer', 280.00);
+
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(170, 1,  NULL, 1500.00,  'debit',  'To savings'),
+(170, 6,  NULL, 1500.00,  'credit', 'From checking'),
+(171, 1,  NULL, 1000.00,  'debit',  'To brokerage'),
+(171, 10, NULL, 1000.00,  'credit', 'Monthly investment'),
+(172, 1,  NULL, 500.00,   'debit',  'To Roth IRA'),
+(172, 11, NULL, 500.00,   'credit', 'Monthly Roth contribution'),
+(173, 1,  NULL, 700.00,   'debit',  'CC payment'),
+(173, 8,  NULL, 700.00,   'credit', 'Payment received'),
+(174, 2,  NULL, 500.00,   'debit',  'CC payment'),
+(174, 9,  NULL, 500.00,   'credit', 'Payment received'),
+(175, 4,  NULL, 9500.00,  'debit',  'Withdraw to bank'),
+(175, 2,  NULL, 9500.00,  'credit', 'From Stripe'),
+(176, 5,  NULL, 2500.00,  'debit',  'Withdraw to bank'),
+(176, 2,  NULL, 2500.00,  'credit', 'From Wise'),
+(177, 3,  NULL, 280.00,   'debit',  'Withdraw to personal'),
+(177, 1,  NULL, 280.00,   'credit', 'From PayPal');
+
+-- Monthly transfer: business to personal for living expenses
+INSERT INTO transactions (id, transaction_date, description, transaction_type, total_amount) VALUES
+(203, '2026-01-02', 'Transfer from Business to Personal', 'transfer', 5500.00);
+INSERT INTO transaction_entries (transaction_id, account_id, category_id, amount, entry_type, description) VALUES
+(203, 2, NULL, 5500.00, 'debit',  'To personal checking'),
+(203, 1, NULL, 5500.00, 'credit', 'From business checking');
+
+-- Set the sequence to max ID
+SELECT setval('transactions_id_seq', 203);
+
+-- =============================================================================
+-- 5. CALCULATE ACCOUNT BALANCES
+-- =============================================================================
+
+-- Reset balances to opening_balance, then apply all entries
+UPDATE accounts a SET current_balance = a.opening_balance + COALESCE((
+    SELECT SUM(CASE WHEN te.entry_type = 'credit' THEN te.amount ELSE -te.amount END)
+    FROM transaction_entries te
+    WHERE te.account_id = a.id
+), 0);
+
+-- =============================================================================
+-- 6. BUDGETS (Dec 2025 – Feb 2026)
+-- =============================================================================
+
+INSERT INTO budgets (category_id, month_year, budgeted_amount) VALUES
+-- December 2025
+(11, '2025-12-01', 1800.00),  -- Rent
+(12, '2025-12-01', 500.00),   -- Groceries
+(13, '2025-12-01', 300.00),   -- Dining Out
+(17, '2025-12-01', 250.00),   -- Software Subscriptions
+(18, '2025-12-01', 400.00),   -- Coworking
+(6,  '2025-12-01', 300.00),   -- Entertainment
+(25, '2025-12-01', 50.00),    -- Streaming
+-- January 2026
+(11, '2026-01-01', 1800.00),  -- Rent
+(12, '2026-01-01', 500.00),   -- Groceries
+(13, '2026-01-01', 300.00),   -- Dining Out
+(17, '2026-01-01', 250.00),   -- Software Subscriptions
+(18, '2026-01-01', 400.00),   -- Coworking
+(6,  '2026-01-01', 200.00),   -- Entertainment
+(25, '2026-01-01', 50.00),    -- Streaming
+(19, '2026-01-01', 500.00),   -- Equipment
+-- February 2026
+(11, '2026-02-01', 1800.00),  -- Rent
+(12, '2026-02-01', 500.00),   -- Groceries
+(13, '2026-02-01', 300.00),   -- Dining Out
+(17, '2026-02-01', 250.00),   -- Software Subscriptions
+(18, '2026-02-01', 400.00),   -- Coworking
+(6,  '2026-02-01', 200.00),   -- Entertainment
+(25, '2026-02-01', 50.00),    -- Streaming
+(19, '2026-02-01', 500.00);   -- Equipment
+
+-- Update actual_amount from transaction entries
+UPDATE budgets b SET actual_amount = COALESCE((
+    SELECT SUM(te.amount)
+    FROM transaction_entries te
+    JOIN transactions t ON te.transaction_id = t.id
+    WHERE te.category_id = b.category_id
+      AND t.transaction_type = 'expense'
+      AND date_trunc('month', t.transaction_date::timestamp) = b.month_year
+), 0);
+
+-- =============================================================================
+-- 7. GRANT PERMISSIONS
+-- =============================================================================
+
+GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO financial_advisor;
+GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO financial_advisor;
+
+-- =============================================================================
+-- Done! Demo database ready.
+-- Run: uv run python app.py
+-- =============================================================================

src/agent/__init__.py

@@ -0,0 +1,3 @@
+from src.agent.graph import create_agent
+
+__all__ = ["create_agent"]

src/agent/graph.py

@@ -0,0 +1,28 @@
+from langgraph.graph import StateGraph, START, END
+from langgraph.prebuilt import ToolNode
+
+from src.agent.state import AgentState
+from src.agent.nodes import call_model, should_continue
+from src.tools import all_tools
+
+
+def create_agent(checkpointer=None):
+    """Create and compile the Cashy agent graph.
+
+    Args:
+        checkpointer: Optional LangGraph checkpointer for conversation persistence.
+
+    Returns:
+        Compiled LangGraph agent.
+    """
+    tool_node = ToolNode(all_tools)
+
+    builder = StateGraph(AgentState)
+    builder.add_node("agent", call_model)
+    builder.add_node("tools", tool_node)
+
+    builder.add_edge(START, "agent")
+    builder.add_conditional_edges("agent", should_continue, {"tools": "tools", END: END})
+    builder.add_edge("tools", "agent")
+
+    return builder.compile(checkpointer=checkpointer)

src/agent/nodes.py

@@ -0,0 +1,194 @@
+import logging
+from datetime import date
+from langchain_core.messages import SystemMessage
+from langgraph.graph import END
+
+from src.agent.state import AgentState
+from src.agent.prompts import get_system_prompt
+from src.config import settings
+from src.tools import all_tools
+
+logger = logging.getLogger("cashy.agent")
+
+# Default models per provider
+DEFAULT_MODELS = {
+    "openai": "gpt-5-mini",
+    "anthropic": "claude-sonnet-4-20250514",
+    "google": "gemini-2.5-flash",
+    "huggingface": "meta-llama/Llama-3.3-70B-Instruct",
+    "free-tier": "Qwen/Qwen2.5-7B-Instruct",
+}
+
+# Capture Space's HF token at startup (before BYOK overwrites it)
+_SPACE_HF_TOKEN = settings.hf_token
+
+
+def create_model():
+    """Create the LLM chat model with tools bound. Supports multiple providers."""
+    provider = settings.resolved_provider
+    if not provider:
+        raise ValueError(
+            "No API key configured. Please select a provider and enter your API key in the sidebar."
+        )
+    model_name = settings.model_name or DEFAULT_MODELS[provider]
+
+    logger.info("Initializing LLM: %s (provider=%s)", model_name, provider)
+
+    if provider == "openai":
+        from langchain_openai import ChatOpenAI
+
+        chat_model = ChatOpenAI(
+            model=model_name,
+            api_key=settings.openai_api_key,
+            max_tokens=settings.model_max_tokens,
+            temperature=settings.model_temperature,
+        )
+
+    elif provider == "anthropic":
+        from langchain_anthropic import ChatAnthropic
+
+        chat_model = ChatAnthropic(
+            model=model_name,
+            api_key=settings.anthropic_api_key,
+            max_tokens=settings.model_max_tokens,
+            temperature=settings.model_temperature,
+        )
+
+    elif provider == "google":
+        from langchain_google_genai import ChatGoogleGenerativeAI
+
+        chat_model = ChatGoogleGenerativeAI(
+            model=model_name,
+            google_api_key=settings.google_api_key,
+            max_output_tokens=settings.model_max_tokens,
+            temperature=settings.model_temperature,
+        )
+
+    elif provider == "free-tier":
+        from langchain_huggingface import ChatHuggingFace, HuggingFaceEndpoint
+
+        model_name = DEFAULT_MODELS["free-tier"]  # always locked
+        llm = HuggingFaceEndpoint(
+            repo_id=model_name,
+            task="text-generation",
+            max_new_tokens=settings.model_max_tokens,
+            huggingfacehub_api_token=_SPACE_HF_TOKEN,
+        )
+        chat_model = ChatHuggingFace(llm=llm)
+
+    elif provider == "huggingface":
+        from langchain_huggingface import ChatHuggingFace, HuggingFaceEndpoint
+
+        llm = HuggingFaceEndpoint(
+            repo_id=model_name,
+            provider=settings.hf_inference_provider,
+            task="text-generation",
+            max_new_tokens=settings.model_max_tokens,
+            huggingfacehub_api_token=settings.hf_token,
+        )
+        chat_model = ChatHuggingFace(llm=llm)
+
+    else:
+        raise ValueError(f"Unknown LLM provider: {provider}")
+
+    tools = _sanitize_tools(all_tools) if provider in ("huggingface", "free-tier") else all_tools
+    model = chat_model.bind_tools(tools)
+    logger.info("Model ready with %d tools bound", len(all_tools))
+    return model
+
+
+# Module-level model instance (created once)
+model_with_tools = None
+
+
+def get_model():
+    global model_with_tools
+    if model_with_tools is None:
+        model_with_tools = create_model()
+    return model_with_tools
+
+
+def reset_model():
+    """Clear the cached model so the next call creates a fresh one."""
+    global model_with_tools
+    model_with_tools = None
+    logger.info("Model cache cleared — next query will reinitialize")
+
+
+def _sanitize_for_latin1(text: str) -> str:
+    """Replace non-latin-1 Unicode characters for HuggingFace's HTTP transport."""
+    result = []
+    for c in text:
+        try:
+            c.encode("latin-1")
+            result.append(c)
+        except UnicodeEncodeError:
+            # Common replacements
+            if c in ("\u2014", "\u2013"):
+                result.append("-")
+            elif c in ("\u201c", "\u201d"):
+                result.append('"')
+            elif c in ("\u2018", "\u2019"):
+                result.append("'")
+            elif c == "\u2026":
+                result.append("...")
+            elif c == "\u2192":
+                result.append("->")
+            else:
+                result.append("?")
+    return "".join(result)
+
+
+def _sanitize_tools(tools: list) -> list:
+    """Return copies of tools with latin-1 safe descriptions."""
+    import copy
+    sanitized = []
+    for tool in tools:
+        t = copy.deepcopy(tool)
+        if hasattr(t, "description"):
+            t.description = _sanitize_for_latin1(t.description)
+        if hasattr(t, "args_schema") and t.args_schema:
+            for field_name, field_info in t.args_schema.model_fields.items():
+                if field_info.description:
+                    field_info.description = _sanitize_for_latin1(field_info.description)
+        sanitized.append(t)
+    return sanitized
+
+
+def call_model(state: AgentState) -> dict:
+    """Invoke the LLM with system prompt and tools."""
+    model = get_model()
+    today = date.today()
+    prompt = get_system_prompt(settings.app_mode).format(today=today.isoformat(), year=today.year)
+    messages = [SystemMessage(content=prompt)] + state["messages"]
+
+    # HuggingFace Inference API requires latin-1 compatible text
+    if settings.resolved_provider in ("huggingface", "free-tier"):
+        logger.debug("Sanitizing %d messages for latin-1 compatibility", len(messages))
+        for msg in messages:
+            if isinstance(msg.content, str):
+                msg.content = _sanitize_for_latin1(msg.content)
+
+    logger.debug("Calling LLM (%d messages in state)", len(state["messages"]))
+
+    response = model.invoke(messages)
+
+    if response.tool_calls:
+        tool_names = [tc["name"] for tc in response.tool_calls]
+        logger.info("LLM requested tools: %s", ", ".join(tool_names))
+        for tc in response.tool_calls:
+            logger.debug("  -> %s(%s)", tc["name"], tc["args"])
+    else:
+        logger.info("LLM final response (%d chars)", len(response.content))
+
+    return {"messages": [response]}
+
+
+def should_continue(state: AgentState) -> str:
+    """Route to tools if the model made tool calls, otherwise end."""
+    last_message = state["messages"][-1]
+    if last_message.tool_calls:
+        logger.debug("Routing to tools node")
+        return "tools"
+    logger.debug("Routing to END")
+    return END

src/agent/prompts.py

@@ -0,0 +1,406 @@
+SYSTEM_PROMPT_DEMO = """\
+You are Cashy, a friendly and knowledgeable personal financial advisor AI that helps users manage their finances through a PostgreSQL database.
+
+**IMPORTANT: Always respond in English.**
+
+**Today's date is {today}.**
+When the user refers to a month without specifying a year, assume the current year ({year}).
+
+## Conversational Behavior
+
+You are a conversational assistant first. Not every message requires a tool call.
+
+- **Greetings** (hello, hi, hey): Respond warmly and briefly explain what you can help with. Do NOT call any tools.
+- **Identity questions** (who are you, what can you do): Answer from your own knowledge. You are Cashy, an AI financial advisor that can check account balances, analyze spending, track budgets, record transactions, and generate charts. Do NOT query the database for this.
+- **General conversation**: Respond naturally. Only use tools when the user asks about their financial data.
+- **Financial questions**: Use the appropriate tool to query real data before responding.
+
+## Available Tools
+
+You have access to these database tools:
+1. **Finance DB Query** - Execute SQL SELECT queries for custom data retrieval
+2. **Get Account Balance** - Retrieve current balance for specific accounts
+3. **Get Recent Transactions** - View transaction history with filters
+4. **Get Spending by Category** - Get spending breakdown by category for a month
+5. **Get All Accounts** - List all accounts with balances and types
+6. **Create Transaction** - Record new income, expense, or transfer transactions
+7. **Update Transaction** - Modify an existing transaction (description, amount, date, category, notes)
+8. **Delete Transaction** - Remove a transaction and all its entries (irreversible)
+9. **Generate Chart** - Create bar, pie, line, or horizontal bar charts from SQL query results. The chart image is displayed directly in the chat.
+
+**IMPORTANT: Prefer the specialized tools (2-8) over Finance DB Query (1).** Only use Finance DB Query when the other tools cannot answer the question.
+
+**IMPORTANT: For write operations (create, update, delete), call the tool directly with all required parameters. Do NOT ask the user to confirm first --the tool itself will pause and show a confirmation prompt to the user automatically.** Just gather the necessary details from the user's message and call the tool.
+
+## Database Schema (Exact Column Names)
+
+When writing SQL queries with Finance DB Query, you MUST use these exact table and column names:
+
+**transactions**: id, transaction_date (date), description (varchar), transaction_type (varchar: 'expense'/'income'/'transfer'), total_amount (numeric), reference_number, notes, created_at
+**transaction_entries**: id, transaction_id (FK), account_id (FK), category_id (FK), amount (numeric), entry_type (varchar: 'debit'/'credit'), description (varchar), created_at
+**accounts**: id, name (varchar), account_type_id (FK), current_balance (numeric), is_active (bool), institution (varchar), currency (varchar), credit_limit, opening_balance
+**account_types**: id, name (varchar --exact values: 'Bank Account', 'Investment', 'Credit Card', 'Cash', 'Loan', 'Savings Account'), description
+**categories**: id, name (varchar), parent_category_id (FK self), category_type (varchar: 'expense'/'income'/'transfer'), is_active (bool)
+**budgets**: id, category_id (FK), month_year (date), budgeted_amount, actual_amount, variance_amount
+
+**Pre-built views (use these for complex queries):**
+- **v_transaction_details**: transaction_id, transaction_date, transaction_description, transaction_type, total_amount, entry_id, account_name, institution, category_name, parent_category_name, entry_amount, entry_type, entry_description, notes
+- **v_monthly_spending**: month_year, category, category_type, total_amount, transaction_count, average_amount
+- **v_account_summary**: id, name, account_type, current_balance, currency, is_active, last_month_balance, monthly_change
+
+**Key relationships:**
+- accounts.account_type_id -> account_types.id
+- transaction_entries.transaction_id -> transactions.id
+- transaction_entries.account_id -> accounts.id
+- transaction_entries.category_id -> categories.id
+- categories.parent_category_id -> categories.id (hierarchy)
+
+## SQL Query Rules (for Finance DB Query)
+
+- ALWAYS include GROUP BY for every non-aggregated column when using SUM, COUNT, AVG, etc.
+- Use the `v_transaction_details` view for transaction queries --it has pre-joined account names, categories, and proper dates. Its columns are: transaction_id, transaction_date, transaction_description, transaction_type, total_amount, entry_id, account_name, institution, category_name, parent_category_name, entry_amount, entry_type, entry_description, notes.
+- Filter by `transaction_date` for date/month queries, NEVER by `created_at` (which is the record insertion timestamp, not the transaction date).
+- Use `v_monthly_spending` view for spending-by-category summaries.
+- When querying budgets, ALWAYS JOIN categories to get category names.
+- Use exact `account_types.name` values listed above --do not guess spelling.
+- When querying spending or expenses, ALWAYS filter `transaction_type = 'expense'` to exclude transfers. Transfers are debits too but have no category and are not spending.
+
+### Example Queries
+
+Monthly spending by category:
+```sql
+SELECT category, total_amount FROM v_monthly_spending
+WHERE month_year = '2026-01-01' AND category_type = 'expense'
+```
+
+Budget vs actual for a month:
+```sql
+SELECT c.name, b.budgeted_amount, b.actual_amount, b.variance_amount
+FROM budgets b JOIN categories c ON b.category_id = c.id
+WHERE b.month_year = '2026-01-01'
+```
+
+Transactions in a category for a month:
+```sql
+SELECT transaction_date, transaction_description, entry_amount, account_name
+FROM v_transaction_details
+WHERE category_name = 'Software Subscriptions'
+  AND EXTRACT(MONTH FROM transaction_date) = 1
+  AND EXTRACT(YEAR FROM transaction_date) = 2026
+```
+
+Accounts by type (e.g., investment accounts):
+```sql
+SELECT name, account_type, current_balance, currency
+FROM v_account_summary
+WHERE account_type = 'Investment' AND is_active = true
+```
+
+Client income for a month:
+```sql
+SELECT transaction_date, transaction_description, entry_amount, account_name
+FROM v_transaction_details
+WHERE category_name = 'Client Invoices'
+  AND EXTRACT(MONTH FROM transaction_date) = 1
+  AND EXTRACT(YEAR FROM transaction_date) = 2026
+```
+
+## Output Format Requirements
+
+**CRITICAL - Follow these formatting rules exactly:**
+
+1. **Currency amounts**: Always format as `$X,XXX.XX` with:
+   - Dollar sign prefix
+   - Comma thousands separator
+   - Exactly two decimal places
+   - Example: `$1,234.56` or `$45,230.50`
+
+2. **Transaction confirmations**: Respond exactly with:
+   - `Transaction recorded` (success)
+   - `Error: [specific error description]` (failure)
+
+3. **Lists and rankings**: Use numbered format:
+   1. Category Name: $X,XXX.XX
+   2. Category Name: $X,XXX.XX
+   3. Category Name: $X,XXX.XX
+
+4. **Dates**: Use ISO format `YYYY-MM-DD` when showing dates explicitly
+
+5. **Account balances**: Respond with just the amount unless context is requested:
+   - Question: "What's the balance on my Chase account?"
+   - Answer: "$8,500.00"
+
+6. **Spending totals**: Provide the number directly:
+   - Question: "How much did I spend on dining out?"
+   - Answer: "$450.00"
+
+## Financial Context (Freelancer Accounts)
+
+The user is a US-based freelance web developer managing both personal and business finances. Their accounts:
+- **Chase**: Personal checking (daily expenses) and Business checking (client payments, business expenses)
+- **PayPal**: Receives client payments, especially from international clients
+- **Stripe**: Receives payments from clients via invoicing platform
+- **Wise**: International client payments and currency conversion
+- **Marcus (Goldman Sachs)**: High-yield savings account (emergency fund)
+- **Chase Sapphire**: Personal credit card (rewards on travel and dining)
+- **Amex Blue**: Business credit card (business expenses)
+- **Fidelity**: Brokerage and Roth IRA (long-term investments and retirement)
+- **Cash**: Physical cash on hand
+
+**Investment queries**: Investments are transfers to/from accounts with `account_type = 'Investment'` (in account_types table). They have `transaction_type = 'transfer'` and typically NO category. To find investment activity, query by account type --not by category:
+```sql
+SELECT t.transaction_date, t.description, te.amount, a.name as account_name
+FROM transactions t
+JOIN transaction_entries te ON te.transaction_id = t.id
+JOIN accounts a ON te.account_id = a.id
+JOIN account_types at ON a.account_type_id = at.id
+WHERE at.name = 'Investment' AND te.entry_type = 'credit'
+  AND EXTRACT(MONTH FROM t.transaction_date) = 1
+  AND EXTRACT(YEAR FROM t.transaction_date) = 2026
+```
+
+## Transaction Recording Rules
+
+When creating transactions:
+1. **Expenses**: Use `entry_type='debit'` on the account, amount is positive
+2. **Income**: Use `entry_type='credit'` on the account, amount is positive
+3. **Transfers**: Create two entries - debit from source, credit to destination
+4. **Category selection**: Match user's description to the closest category name
+5. **Descriptions**: Include key details (client name, project, purpose)
+
+When updating transactions:
+1. Provide the `transaction_id` (get it from recent transactions or a query first)
+2. Only include the fields that need to change --unchanged fields can be omitted
+3. The user will see current values and proposed changes before confirming
+
+When deleting transactions:
+1. Provide the `transaction_id` --always look it up first, never guess
+2. Deletion removes the transaction AND all its entries (irreversible)
+3. The user will see the full transaction details before confirming
+
+## Advisory Responses
+
+When the user asks for financial advice or recommendations, ALWAYS query relevant data first and base your response on actual numbers. Never give generic advice without checking the data.
+
+**Example --User asks: "I need to buy a $1,500 laptop for work, can I afford it?"**
+
+Steps the agent MUST follow (use multiple tool calls, do NOT stop after the first one):
+1. Query liquid account balances -> `SELECT name, current_balance FROM v_account_summary WHERE account_type IN ('Bank Account', 'Cash') AND is_active = true`
+2. Query ALL budgets for this month -> `SELECT c.name, b.budgeted_amount, b.actual_amount, b.variance_amount FROM budgets b JOIN categories c ON b.category_id = c.id WHERE b.month_year = '2026-01-01'`
+3. Calculate the impact of the $1,500 on each relevant budget category
+4. Suggest which specific account to use based on balances
+
+Expected response style:
+"Your available liquid accounts:
+- Chase Business Checking: $X
+- Chase Personal Checking: $X
+- PayPal: $X
+- Cash: $350.00
+
+Your budget for this month:
+- Equipment: budgeted $500.00, spent $0.00, available $500.00
+- Software Subscriptions: budgeted $250.00, spent $180.00, available $70.00
+
+The $1,500 laptop exceeds your Equipment budget by $1,000. However, since it's a business expense, you could use your Chase Business Checking ($X available).
+
+Since this is a work laptop, it's tax-deductible as a business expense. Consider paying with Amex Blue to earn rewards on the purchase."
+
+**Key rules:**
+- ALWAYS query multiple data points: liquid balances, budgets, and current spending
+- Distinguish between personal and business accounts
+- For budget questions: compare budgeted_amount vs actual_amount and show remaining room
+- For purchase decisions: show exact budget impact AND suggest which account to use
+- Always show specific numbers, never give generic tips like "review your spending habits"
+- For business expenses, mention tax deduction implications when relevant
+
+## Chart Generation Rules
+
+When the user asks for a visualization, chart, graph, or plot:
+1. Use the **Generate Chart** tool with an appropriate chart_type
+2. The sql_query must be a valid SELECT that returns the data to visualize
+3. x_column and y_column must match exact column names from the query result
+4. For comparison charts (e.g., budget vs actual), use y2_column for the second series --this creates grouped bars or a second line
+5. After the chart is generated, briefly describe the key insights from the data
+
+Chart type selection:
+- **bar**: Comparing categories (spending by category, budget vs actual)
+- **horizontal_bar**: When category labels are long (account names, descriptions)
+- **pie**: Showing proportions or distribution (% of total spending)
+- **line**: Trends over time (monthly spending, balance history)
+
+Comparison chart example (budget vs actual):
+```
+generate_chart(
+  chart_type="bar",
+  title="Budget vs Actual - January 2026",
+  sql_query="SELECT c.name, b.budgeted_amount, b.actual_amount FROM budgets b JOIN categories c ON b.category_id = c.id WHERE b.month_year = '2026-01-01'",
+  x_column="name",
+  y_column="budgeted_amount",
+  y2_column="actual_amount"
+)
+```
+
+Do NOT generate a chart unless the user explicitly asks for a visual, chart, graph, or plot. For normal data questions, respond with text and numbers.
+
+## Response Guidelines
+
+- **Be concise**: Provide the requested information without unnecessary elaboration
+- **Be accurate**: Use exact numbers from the database
+- **Be helpful**: If a query is ambiguous, make a reasonable assumption and state it
+- **Be consistent**: Always follow the output format rules above
+- **Write operations**: Call the tool directly --it handles user confirmation automatically
+- **NEVER show SQL queries in your responses**. Use the tools to execute queries silently and only present the results to the user. Do not describe what query you will run --just run it.
+- **Always execute tools immediately**. Do not say "let me run this query" or "let's check" --call the tool in the same turn.
+
+## Error Handling
+
+If you cannot fulfill a request:
+1. State clearly what information is missing or why it cannot be done
+2. Suggest what the user should provide or clarify
+3. Never make up data or fabricate transactions\
+"""
+
+SYSTEM_PROMPT_PERSONAL = """\
+You are Cashy, a friendly and knowledgeable personal financial advisor AI that helps users manage their finances through a PostgreSQL database.
+
+**IMPORTANT: Always respond in English.**
+
+**Today's date is {today}.**
+When the user refers to a month without specifying a year, assume the current year ({year}).
+
+## Conversational Behavior
+
+You are a conversational assistant first. Not every message requires a tool call.
+
+- **Greetings** (hello, hi, hey): Respond warmly and briefly explain what you can help with. Do NOT call any tools.
+- **Identity questions** (who are you, what can you do): Answer from your own knowledge. You are Cashy, an AI financial advisor that can check account balances, analyze spending, track budgets, record transactions, and generate charts. Do NOT query the database for this.
+- **General conversation**: Respond naturally. Only use tools when the user asks about their financial data.
+- **Financial questions**: Use the appropriate tool to query real data before responding.
+
+## Available Tools
+
+You have access to these database tools:
+1. **Finance DB Query** - Execute SQL SELECT queries for custom data retrieval
+2. **Get Account Balance** - Retrieve current balance for specific accounts
+3. **Get Recent Transactions** - View transaction history with filters
+4. **Get Spending by Category** - Get spending breakdown by category for a month
+5. **Get All Accounts** - List all accounts with balances and types
+6. **Create Transaction** - Record new income, expense, or transfer transactions
+7. **Update Transaction** - Modify an existing transaction (description, amount, date, category, notes)
+8. **Delete Transaction** - Remove a transaction and all its entries (irreversible)
+9. **Generate Chart** - Create bar, pie, line, or horizontal bar charts from SQL query results. The chart image is displayed directly in the chat.
+
+**IMPORTANT: Prefer the specialized tools (2-8) over Finance DB Query (1).** Only use Finance DB Query when the other tools cannot answer the question.
+
+**IMPORTANT: For write operations (create, update, delete), call the tool directly with all required parameters. Do NOT ask the user to confirm first --the tool itself will pause and show a confirmation prompt to the user automatically.** Just gather the necessary details from the user's message and call the tool.
+
+## Database Schema (Exact Column Names)
+
+When writing SQL queries with Finance DB Query, you MUST use these exact table and column names:
+
+**transactions**: id, transaction_date (date), description (varchar), transaction_type (varchar: 'expense'/'income'/'transfer'), total_amount (numeric), reference_number, notes, created_at
+**transaction_entries**: id, transaction_id (FK), account_id (FK), category_id (FK), amount (numeric), entry_type (varchar: 'debit'/'credit'), description (varchar), created_at
+**accounts**: id, name (varchar), account_type_id (FK), current_balance (numeric), is_active (bool), institution (varchar), currency (varchar), credit_limit, opening_balance
+**account_types**: id, name (varchar --exact values: 'Bank Account', 'Investment', 'Credit Card', 'Cash', 'Loan', 'Savings Account'), description
+**categories**: id, name (varchar), parent_category_id (FK self), category_type (varchar: 'expense'/'income'/'transfer'), is_active (bool)
+**budgets**: id, category_id (FK), month_year (date), budgeted_amount, actual_amount, variance_amount
+
+**Pre-built views (use these for complex queries):**
+- **v_transaction_details**: transaction_id, transaction_date, transaction_description, transaction_type, total_amount, entry_id, account_name, institution, category_name, parent_category_name, entry_amount, entry_type, entry_description, notes
+- **v_monthly_spending**: month_year, category, category_type, total_amount, transaction_count, average_amount
+- **v_account_summary**: id, name, account_type, current_balance, currency, is_active, last_month_balance, monthly_change
+
+**Key relationships:**
+- accounts.account_type_id -> account_types.id
+- transaction_entries.transaction_id -> transactions.id
+- transaction_entries.account_id -> accounts.id
+- transaction_entries.category_id -> categories.id
+- categories.parent_category_id -> categories.id (hierarchy)
+
+## SQL Query Rules (for Finance DB Query)
+
+- ALWAYS include GROUP BY for every non-aggregated column when using SUM, COUNT, AVG, etc.
+- Use the `v_transaction_details` view for transaction queries --it has pre-joined account names, categories, and proper dates.
+- Filter by `transaction_date` for date/month queries, NEVER by `created_at` (which is the record insertion timestamp, not the transaction date).
+- Use `v_monthly_spending` view for spending-by-category summaries.
+- When querying budgets, ALWAYS JOIN categories to get category names.
+- Use exact `account_types.name` values listed above --do not guess spelling.
+- When querying spending or expenses, ALWAYS filter `transaction_type = 'expense'` to exclude transfers. Transfers are debits too but have no category and are not spending.
+
+## Output Format Requirements
+
+**CRITICAL - Follow these formatting rules exactly:**
+
+1. **Currency amounts**: Always format as `$X,XXX.XX` with dollar sign, comma separator, two decimals.
+2. **Transaction confirmations**: `Transaction recorded` (success) or `Error: [description]` (failure).
+3. **Lists and rankings**: Use numbered format with amounts.
+4. **Dates**: Use ISO format `YYYY-MM-DD`.
+5. **Account balances**: Respond with just the amount unless context is requested.
+6. **Spending totals**: Provide the number directly.
+
+## Financial Context
+
+The user is managing their personal finances. Start by discovering their accounts and data using the available tools --do NOT assume account names, institutions, or categories. Use `get_all_accounts` to learn the account structure before answering account-specific questions.
+
+**Investment queries**: Investments are transfers to/from accounts with `account_type = 'Investment'`. They have `transaction_type = 'transfer'` and typically NO category. Query by account type, not by category.
+
+## Transaction Recording Rules
+
+When creating transactions:
+1. **Expenses**: Use `entry_type='debit'` on the account, amount is positive
+2. **Income**: Use `entry_type='credit'` on the account, amount is positive
+3. **Transfers**: Create two entries - debit from source, credit to destination
+4. **Category selection**: Match user's description to the closest category name
+5. **Descriptions**: Include key details (client name, project, purpose)
+
+When updating transactions:
+1. Provide the `transaction_id` (get it from recent transactions or a query first)
+2. Only include the fields that need to change --unchanged fields can be omitted
+3. The user will see current values and proposed changes before confirming
+
+When deleting transactions:
+1. Provide the `transaction_id` --always look it up first, never guess
+2. Deletion removes the transaction AND all its entries (irreversible)
+3. The user will see the full transaction details before confirming
+
+## Advisory Responses
+
+When the user asks for financial advice or recommendations, ALWAYS query relevant data first and base your response on actual numbers. Never give generic advice without checking the data. Query multiple data points: liquid balances, budgets, and current spending. Always show specific numbers.
+
+## Chart Generation Rules
+
+When the user asks for a visualization, chart, graph, or plot:
+1. Use the **Generate Chart** tool with an appropriate chart_type
+2. The sql_query must be a valid SELECT that returns the data to visualize
+3. x_column and y_column must match exact column names from the query result
+4. For comparison charts, use y2_column for the second series
+5. After the chart is generated, briefly describe the key insights
+
+Chart type selection: bar (categories), horizontal_bar (long labels), pie (proportions), line (trends over time).
+
+Do NOT generate a chart unless the user explicitly asks for a visual, chart, graph, or plot.
+
+## Response Guidelines
+
+- **Be concise**: Provide the requested information without unnecessary elaboration
+- **Be accurate**: Use exact numbers from the database
+- **Be helpful**: If a query is ambiguous, make a reasonable assumption and state it
+- **Be consistent**: Always follow the output format rules above
+- **Write operations**: Call the tool directly --it handles user confirmation automatically
+- **NEVER show SQL queries in your responses**. Use the tools to execute queries silently and only present the results to the user. Do not describe what query you will run --just run it.
+- **Always execute tools immediately**. Do not say "let me run this query" or "let's check" --call the tool in the same turn.
+
+## Error Handling
+
+If you cannot fulfill a request:
+1. State clearly what information is missing or why it cannot be done
+2. Suggest what the user should provide or clarify
+3. Never make up data or fabricate transactions\
+"""
+
+
+def get_system_prompt(mode: str) -> str:
+    """Return the system prompt for the given app mode."""
+    if mode == "personal":
+        return SYSTEM_PROMPT_PERSONAL
+    return SYSTEM_PROMPT_DEMO

src/agent/state.py

@@ -0,0 +1,7 @@
+from langgraph.graph import MessagesState
+
+
+class AgentState(MessagesState):
+    """Agent state extending MessagesState.
+    Add custom keys here if needed later (e.g., user_id, session metadata)."""
+    pass

src/config.py

@@ -0,0 +1,96 @@
+from typing import Literal, Optional
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    # App mode — "demo" (seeded showcase) or "personal" (real financial data)
+    app_mode: Literal["demo", "personal"] = "personal"
+
+    # Database — auto-reads DB_HOST, DB_PORT, etc. from .env
+    db_host: str = "localhost"
+    db_port: int = 5432
+    db_name: str = "financial_db"  # fallback; overridden by resolved_db_name
+    db_name_demo: str = "cashy_demo"
+    db_name_personal: str = "financial_db"
+    db_user: str = "financial_advisor"
+    db_password: str = ""
+    db_sslmode: str = ""  # "require" for Neon; empty for local
+
+    # LLM provider — set explicitly or auto-detected from API keys
+    llm_provider: Optional[Literal["openai", "anthropic", "google", "huggingface", "free-tier", ""]] = None
+
+    # Per-provider API keys (only one needed)
+    openai_api_key: str = ""
+    anthropic_api_key: str = ""
+    google_api_key: str = ""
+    hf_token: str = ""
+
+    # Model configuration
+    model_name: str = ""  # Optional override; defaults per provider
+    model_max_tokens: int = 512
+    model_temperature: float = 0.1
+
+    # HuggingFace-specific
+    hf_inference_provider: str = "together"
+
+    # LangSmith — auto-reads LANGSMITH_* from .env
+    langsmith_tracing: str = "true"
+    langsmith_api_key: str = ""
+    langsmith_project: str = "cashy-financial-advisor"
+
+    # App
+    environment: str = "development"
+    debug: bool = True
+
+    @property
+    def resolved_db_name(self) -> str:
+        """Return the database name based on app_mode."""
+        if self.app_mode == "demo":
+            return self.db_name_demo
+        return self.db_name_personal
+
+    @property
+    def database_url(self) -> str:
+        """Build DATABASE_URL from individual DB components."""
+        url = (
+            f"postgresql://{self.db_user}:{self.db_password}"
+            f"@{self.db_host}:{self.db_port}/{self.resolved_db_name}"
+        )
+        if self.db_sslmode:
+            url += f"?sslmode={self.db_sslmode}"
+        return url
+
+    @property
+    def database_url_safe(self) -> str:
+        """Database URL with password redacted for logging."""
+        return self.database_url.replace(f":{self.db_password}@", ":***@")
+
+    @property
+    def resolved_provider(self) -> Optional[str]:
+        """Return the active LLM provider: explicit setting, auto-detected from keys, or None."""
+        if self.llm_provider and self.llm_provider != "":
+            return self.llm_provider
+
+        # Auto-detect from populated API keys (priority order)
+        if self.openai_api_key and self.openai_api_key != "sk-...":
+            return "openai"
+        if self.anthropic_api_key and self.anthropic_api_key != "sk-ant-...":
+            return "anthropic"
+        if self.google_api_key and self.google_api_key != "AI...":
+            return "google"
+        if self.hf_token and self.hf_token != "hf_...":
+            # In demo mode, default to free-tier (user can switch to huggingface BYOK)
+            if self.app_mode == "demo":
+                return "free-tier"
+            return "huggingface"
+
+        return None
+
+
+settings = Settings()

src/db/connection.py

@@ -0,0 +1,54 @@
+import time
+import logging
+import psycopg2
+from contextlib import contextmanager
+from src.config import settings
+
+logger = logging.getLogger("cashy.db")
+
+NEON_RETRY_DELAY = 3  # seconds to wait for Neon cold start
+
+
+def _connect():
+    """Create a psycopg2 connection, retrying once on cold-start failures."""
+    conn_kwargs = dict(
+        host=settings.db_host,
+        port=settings.db_port,
+        dbname=settings.resolved_db_name,
+        user=settings.db_user,
+        password=settings.db_password,
+    )
+    if settings.db_sslmode:
+        conn_kwargs["sslmode"] = settings.db_sslmode
+
+    try:
+        return psycopg2.connect(**conn_kwargs)
+    except psycopg2.OperationalError:
+        logger.info("DB connection failed -- retrying in %ds (Neon cold start?)", NEON_RETRY_DELAY)
+        time.sleep(NEON_RETRY_DELAY)
+        return psycopg2.connect(**conn_kwargs)
+
+
+@contextmanager
+def get_connection():
+    """Context manager for database connections.
+
+    Usage:
+        with get_connection() as conn:
+            with conn.cursor() as cur:
+                cur.execute("SELECT ...")
+                rows = cur.fetchall()
+    """
+    logger.debug("Opening DB connection")
+    conn = _connect()
+    try:
+        yield conn
+    except Exception:
+        logger.warning("DB error -- rolling back")
+        conn.rollback()
+        raise
+    else:
+        conn.commit()
+    finally:
+        conn.close()
+        logger.debug("DB connection closed")

src/tools/__init__.py

@@ -0,0 +1,21 @@
+from src.tools.finance_query import finance_db_query
+from src.tools.account_balance import get_account_balance
+from src.tools.recent_transactions import get_recent_transactions
+from src.tools.spending_by_category import get_spending_by_category
+from src.tools.all_accounts import get_all_accounts
+from src.tools.create_transaction import create_transaction
+from src.tools.update_transaction import update_transaction
+from src.tools.delete_transaction import delete_transaction
+from src.tools.generate_chart import generate_chart
+
+all_tools = [
+    finance_db_query,
+    get_account_balance,
+    get_recent_transactions,
+    get_spending_by_category,
+    get_all_accounts,
+    create_transaction,
+    update_transaction,
+    delete_transaction,
+    generate_chart,
+]

src/tools/account_balance.py

@@ -0,0 +1,48 @@
+import json
+import logging
+from langchain_core.tools import tool
+from src.db.connection import get_connection
+
+logger = logging.getLogger("cashy.tools")
+
+
+@tool
+def get_account_balance(account_name: str) -> str:
+    """Get the current balance for a specific account by name (e.g., 'BBVA', 'NU', 'Santander')."""
+    logger.info("[get_account_balance] account_name=%s", account_name)
+    try:
+        with get_connection() as conn:
+            with conn.cursor() as cur:
+                cur.execute(
+                    """
+                    SELECT a.name, a.current_balance, at.name as account_type,
+                           a.currency, a.institution
+                    FROM accounts a
+                    JOIN account_types at ON a.account_type_id = at.id
+                    WHERE a.name ILIKE %s AND a.is_active = true
+                    """,
+                    (f"%{account_name}%",),
+                )
+                result = cur.fetchone()
+
+                if result:
+                    logger.info("[get_account_balance] Found: %s = %s %s", result[0], result[1], result[3])
+                    return json.dumps(
+                        {
+                            "success": True,
+                            "account_name": result[0],
+                            "balance": float(result[1]),
+                            "account_type": result[2],
+                            "currency": result[3],
+                            "institution": result[4] or "N/A",
+                        },
+                        default=str,
+                    )
+                else:
+                    logger.warning("[get_account_balance] Account '%s' not found", account_name)
+                    return json.dumps(
+                        {"success": False, "error": f"Account '{account_name}' not found"}
+                    )
+    except Exception as e:
+        logger.error("[get_account_balance] Error: %s", e)
+        return json.dumps({"success": False, "error": str(e)})

src/tools/all_accounts.py

@@ -0,0 +1,38 @@
+import json
+import logging
+from langchain_core.tools import tool
+from src.db.connection import get_connection
+
+logger = logging.getLogger("cashy.tools")
+
+
+@tool
+def get_all_accounts(include_inactive: bool = False) -> str:
+    """Get a list of all user accounts with their balances, types, and institutions."""
+    logger.info("[get_all_accounts] include_inactive=%s", include_inactive)
+    try:
+        with get_connection() as conn:
+            with conn.cursor() as cur:
+                query = """
+                    SELECT a.name, a.current_balance, at.name as account_type,
+                           a.currency, a.institution, a.is_active
+                    FROM accounts a
+                    JOIN account_types at ON a.account_type_id = at.id
+                """
+                if not include_inactive:
+                    query += " WHERE a.is_active = true"
+                query += " ORDER BY at.name, a.name"
+
+                cur.execute(query)
+                columns = [desc[0] for desc in cur.description]
+                rows = cur.fetchall()
+                results = [dict(zip(columns, row)) for row in rows]
+
+                logger.info("[get_all_accounts] Returned %d accounts", len(results))
+                return json.dumps(
+                    {"success": True, "count": len(results), "accounts": results},
+                    default=str,
+                )
+    except Exception as e:
+        logger.error("[get_all_accounts] Error: %s", e)
+        return json.dumps({"success": False, "error": str(e)})

src/tools/create_transaction.py

@@ -0,0 +1,144 @@
+import json
+import logging
+from datetime import datetime
+from langchain_core.tools import tool
+from langgraph.types import interrupt
+from src.db.connection import get_connection
+
+logger = logging.getLogger("cashy.tools")
+
+
+@tool
+def create_transaction(
+    transaction_type: str,
+    transaction_description: str,
+    amount: float,
+    account_name: str,
+    category_name: str = "",
+    date: str = "",
+    notes: str = "",
+) -> str:
+    """Create a new financial transaction (expense, income, or transfer).
+    transaction_type must be 'expense', 'income', or 'transfer'.
+    amount must be a positive number.
+    date format: YYYY-MM-DD (optional, defaults to today).
+    The user will be asked to confirm before the transaction is created."""
+    logger.info("[create_transaction] type=%s amount=%.2f account=%s category=%s",
+                transaction_type, amount, account_name, category_name or "none")
+
+    # --- Validation ---
+    if amount <= 0:
+        return json.dumps({"success": False, "error": "Amount must be positive"})
+
+    if transaction_type not in ("expense", "income", "transfer"):
+        return json.dumps(
+            {"success": False, "error": "transaction_type must be 'expense', 'income', or 'transfer'"}
+        )
+
+    if date and date.strip():
+        try:
+            transaction_date = datetime.strptime(date.strip(), "%Y-%m-%d").date()
+        except ValueError:
+            return json.dumps({"success": False, "error": "Invalid date format. Use YYYY-MM-DD"})
+    else:
+        transaction_date = datetime.now().date()
+
+    # --- Resolve names to IDs ---
+    try:
+        with get_connection() as conn:
+            with conn.cursor() as cur:
+                cur.execute(
+                    "SELECT id, name FROM accounts WHERE name ILIKE %s AND is_active = true",
+                    (f"%{account_name}%",),
+                )
+                account = cur.fetchone()
+                if not account:
+                    return json.dumps(
+                        {"success": False, "error": f"Account '{account_name}' not found"}
+                    )
+                account_id, account_full_name = account
+
+                category_id = None
+                category_full_name = "Uncategorized"
+                if category_name and category_name.strip():
+                    cur.execute(
+                        "SELECT id, name FROM categories WHERE name ILIKE %s AND is_active = true",
+                        (f"%{category_name}%",),
+                    )
+                    category = cur.fetchone()
+                    if category:
+                        category_id, category_full_name = category
+    except Exception as e:
+        logger.error("[create_transaction] Lookup error: %s", e)
+        return json.dumps({"success": False, "error": str(e)})
+
+    entry_type = "credit" if transaction_type == "income" else "debit"
+    desc = transaction_description.strip()
+    note = notes.strip() if notes and notes.strip() else None
+
+    # --- Confirmation gate ---
+    confirmation = {
+        "action": "create_transaction",
+        "message": f"Create {transaction_type} of ${amount:.2f} on {account_full_name}?",
+        "details": {
+            "type": transaction_type,
+            "amount": float(amount),
+            "account": account_full_name,
+            "category": category_full_name,
+            "date": str(transaction_date),
+            "description": desc,
+        },
+    }
+    response = interrupt(confirmation)
+
+    if not response.get("approved"):
+        logger.info("[create_transaction] Cancelled by user")
+        return json.dumps({"success": False, "message": "Transaction cancelled by user"})
+
+    # --- Execute DB write ---
+    try:
+        with get_connection() as conn:
+            with conn.cursor() as cur:
+                cur.execute(
+                    """
+                    INSERT INTO transactions
+                    (transaction_date, description, transaction_type, total_amount, notes)
+                    VALUES (%s, %s, %s, %s, %s)
+                    RETURNING id
+                    """,
+                    (transaction_date, desc, transaction_type, amount, note),
+                )
+                transaction_id = cur.fetchone()[0]
+
+                cur.execute(
+                    """
+                    INSERT INTO transaction_entries
+                    (transaction_id, account_id, category_id, amount, entry_type, description)
+                    VALUES (%s, %s, %s, %s, %s, %s)
+                    RETURNING id
+                    """,
+                    (transaction_id, account_id, category_id, amount, entry_type, desc),
+                )
+                entry_id = cur.fetchone()[0]
+
+                logger.info("[create_transaction] Created txn_id=%d entry_id=%d", transaction_id, entry_id)
+                return json.dumps(
+                    {
+                        "success": True,
+                        "transaction_id": transaction_id,
+                        "entry_id": entry_id,
+                        "message": f"{transaction_type.title()} of ${amount:.2f} recorded on {transaction_date}",
+                        "details": {
+                            "type": transaction_type,
+                            "amount": float(amount),
+                            "account": account_full_name,
+                            "category": category_full_name,
+                            "date": str(transaction_date),
+                            "description": desc,
+                        },
+                    },
+                    default=str,
+                )
+    except Exception as e:
+        logger.error("[create_transaction] Error: %s", e)
+        return json.dumps({"success": False, "error": str(e)})

src/tools/delete_transaction.py

@@ -0,0 +1,91 @@
+import json
+import logging
+from langchain_core.tools import tool
+from langgraph.types import interrupt
+from src.db.connection import get_connection
+
+logger = logging.getLogger("cashy.tools")
+
+
+@tool
+def delete_transaction(transaction_id: int) -> str:
+    """Delete a transaction and all its entries. This is irreversible.
+    The user will be asked to confirm before the deletion is executed."""
+    logger.info("[delete_transaction] id=%d", transaction_id)
+
+    # Fetch transaction details for confirmation display
+    try:
+        with get_connection() as conn:
+            with conn.cursor() as cur:
+                cur.execute(
+                    """
+                    SELECT t.id, t.transaction_date, t.description, t.transaction_type,
+                           t.total_amount, a.name as account_name, c.name as category_name
+                    FROM transactions t
+                    JOIN transaction_entries te ON te.transaction_id = t.id
+                    JOIN accounts a ON te.account_id = a.id
+                    LEFT JOIN categories c ON te.category_id = c.id
+                    WHERE t.id = %s
+                    LIMIT 1
+                    """,
+                    (transaction_id,),
+                )
+                row = cur.fetchone()
+                if not row:
+                    return json.dumps({"success": False, "error": f"Transaction {transaction_id} not found"})
+
+                details = {
+                    "id": row[0],
+                    "date": str(row[1]),
+                    "description": row[2],
+                    "type": row[3],
+                    "amount": float(row[4]),
+                    "account": row[5],
+                    "category": row[6] or "Uncategorized",
+                }
+
+                # Count entries that will be deleted
+                cur.execute(
+                    "SELECT COUNT(*) FROM transaction_entries WHERE transaction_id = %s",
+                    (transaction_id,),
+                )
+                entry_count = cur.fetchone()[0]
+
+    except Exception as e:
+        logger.error("[delete_transaction] Lookup error: %s", e)
+        return json.dumps({"success": False, "error": str(e)})
+
+    # --- Confirmation gate ---
+    confirmation = {
+        "action": "delete_transaction",
+        "message": f"Delete transaction #{transaction_id} and {entry_count} entries?",
+        "details": details,
+        "entries_to_delete": entry_count,
+    }
+    response = interrupt(confirmation)
+
+    if not response.get("approved"):
+        logger.info("[delete_transaction] Cancelled by user")
+        return json.dumps({"success": False, "message": "Deletion cancelled by user"})
+
+    # --- Execute the delete (CASCADE handles transaction_entries) ---
+    try:
+        with get_connection() as conn:
+            with conn.cursor() as cur:
+                cur.execute("DELETE FROM transactions WHERE id = %s", (transaction_id,))
+                if cur.rowcount == 0:
+                    return json.dumps({"success": False, "error": f"Transaction {transaction_id} not found"})
+
+                logger.info("[delete_transaction] Deleted txn_id=%d (%d entries)", transaction_id, entry_count)
+                return json.dumps(
+                    {
+                        "success": True,
+                        "transaction_id": transaction_id,
+                        "message": f"Transaction #{transaction_id} deleted along with {entry_count} entries",
+                        "entries_deleted": entry_count,
+                    },
+                    default=str,
+                )
+    except Exception as e:
+        logger.error("[delete_transaction] Error: %s", e)
+        return json.dumps({"success": False, "error": str(e)})

src/tools/finance_query.py

@@ -0,0 +1,32 @@
+import json
+import logging
+from langchain_core.tools import tool
+from src.db.connection import get_connection
+
+logger = logging.getLogger("cashy.tools")
+
+
+@tool
+def finance_db_query(query: str) -> str:
+    """Execute a SQL SELECT query on the financial database. Only SELECT queries are allowed.
+    Use this for custom queries not covered by the other tools."""
+    logger.info("[finance_db_query] SQL: %s", query[:120])
+    if not query.strip().upper().startswith("SELECT"):
+        logger.warning("[finance_db_query] Rejected non-SELECT query")
+        return json.dumps({"error": "Only SELECT queries allowed"})
+
+    try:
+        with get_connection() as conn:
+            with conn.cursor() as cur:
+                cur.execute(query)
+                columns = [desc[0] for desc in cur.description]
+                rows = cur.fetchall()
+                results = [dict(zip(columns, row)) for row in rows]
+                logger.info("[finance_db_query] Returned %d rows", len(results))
+                return json.dumps(
+                    {"success": True, "count": len(results), "data": results},
+                    default=str,
+                )
+    except Exception as e:
+        logger.error("[finance_db_query] Error: %s", e)
+        return json.dumps({"error": str(e)})

src/tools/generate_chart.py

@@ -0,0 +1,212 @@
+import json
+import logging
+import tempfile
+from decimal import Decimal
+
+import numpy as np
+import matplotlib
+matplotlib.use("Agg")  # Non-interactive backend (no display needed)
+import matplotlib.pyplot as plt
+import matplotlib.ticker as ticker
+
+from langchain_core.tools import tool
+from src.db.connection import get_connection
+
+logger = logging.getLogger("cashy.tools")
+
+# Consistent color palette for Cashy charts
+COLORS = [
+    "#2196F3",  # blue
+    "#4CAF50",  # green
+    "#FF9800",  # orange
+    "#E91E63",  # pink
+    "#9C27B0",  # purple
+    "#00BCD4",  # cyan
+    "#FFC107",  # amber
+    "#607D8B",  # blue-grey
+    "#F44336",  # red
+    "#8BC34A",  # light green
+    "#3F51B5",  # indigo
+    "#795548",  # brown
+]
+
+VALID_CHART_TYPES = ("bar", "horizontal_bar", "pie", "line")
+
+
+def _format_currency(x, _pos):
+    """Format axis values as $X,XXX."""
+    return f"${x:,.0f}"
+
+
+def _to_float(val):
+    """Convert Decimal or other numeric types to float for matplotlib."""
+    if isinstance(val, Decimal):
+        return float(val)
+    return float(val)
+
+
+@tool
+def generate_chart(
+    chart_type: str,
+    title: str,
+    sql_query: str,
+    x_column: str,
+    y_column: str,
+    y2_column: str = "",
+    x_label: str = "",
+    y_label: str = "",
+) -> str:
+    """Generate a chart from SQL query results and return the image path.
+
+    Args:
+        chart_type: Type of chart - "bar", "horizontal_bar", "pie", or "line"
+        title: Chart title displayed at the top
+        sql_query: SELECT query to fetch the chart data
+        x_column: Column name for x-axis (categories/labels)
+        y_column: Column name for y-axis (first series of values)
+        y2_column: Optional second column for comparison charts (e.g., budget vs actual). Creates grouped bars or a second line.
+        x_label: Optional label for x-axis
+        y_label: Optional label for y-axis
+    """
+    logger.info("[generate_chart] type=%s, title=%s", chart_type, title)
+    logger.info("[generate_chart] SQL: %s", sql_query[:120])
+
+    # Validate chart type
+    if chart_type not in VALID_CHART_TYPES:
+        return json.dumps({
+            "success": False,
+            "error": f"Invalid chart_type '{chart_type}'. Must be one of: {', '.join(VALID_CHART_TYPES)}",
+        })
+
+    # Validate SQL is SELECT-only
+    if not sql_query.strip().upper().startswith("SELECT"):
+        logger.warning("[generate_chart] Rejected non-SELECT query")
+        return json.dumps({"success": False, "error": "Only SELECT queries allowed"})
+
+    try:
+        # Execute query
+        with get_connection() as conn:
+            with conn.cursor() as cur:
+                cur.execute(sql_query)
+                columns = [desc[0] for desc in cur.description]
+                rows = cur.fetchall()
+
+        if not rows:
+            return json.dumps({"success": False, "error": "Query returned no data"})
+
+        # Validate column names exist in results
+        for col_name, col_label in [(x_column, "x_column"), (y_column, "y_column")]:
+            if col_name not in columns:
+                return json.dumps({
+                    "success": False,
+                    "error": f"{col_label} '{col_name}' not found. Available: {columns}",
+                })
+
+        has_y2 = bool(y2_column)
+        if has_y2 and y2_column not in columns:
+            return json.dumps({
+                "success": False,
+                "error": f"y2_column '{y2_column}' not found. Available: {columns}",
+            })
+
+        x_idx = columns.index(x_column)
+        y_idx = columns.index(y_column)
+
+        labels = [str(row[x_idx]) for row in rows]
+        values = [_to_float(row[y_idx]) for row in rows]
+
+        values2 = None
+        if has_y2:
+            y2_idx = columns.index(y2_column)
+            values2 = [_to_float(row[y2_idx]) for row in rows]
+
+        logger.info("[generate_chart] %d data points, y2=%s", len(labels), has_y2)
+
+        # Generate chart
+        fig, ax = plt.subplots(figsize=(10, 6))
+        colors = COLORS[: len(labels)]
+
+        if chart_type == "bar":
+            if has_y2:
+                # Grouped bar chart
+                x_pos = np.arange(len(labels))
+                width = 0.35
+                ax.bar(x_pos - width / 2, values, width, label=y_column.replace("_", " ").title(), color=COLORS[0])
+                ax.bar(x_pos + width / 2, values2, width, label=y2_column.replace("_", " ").title(), color=COLORS[1])
+                ax.set_xticks(x_pos)
+                ax.set_xticklabels(labels, rotation=45, ha="right")
+                ax.legend()
+            else:
+                ax.bar(labels, values, color=colors)
+                plt.xticks(rotation=45, ha="right")
+            ax.yaxis.set_major_formatter(ticker.FuncFormatter(_format_currency))
+            if x_label:
+                ax.set_xlabel(x_label)
+            if y_label:
+                ax.set_ylabel(y_label)
+
+        elif chart_type == "horizontal_bar":
+            if has_y2:
+                y_pos = np.arange(len(labels))
+                height = 0.35
+                ax.barh(y_pos - height / 2, values, height, label=y_column.replace("_", " ").title(), color=COLORS[0])
+                ax.barh(y_pos + height / 2, values2, height, label=y2_column.replace("_", " ").title(), color=COLORS[1])
+                ax.set_yticks(y_pos)
+                ax.set_yticklabels(labels)
+                ax.legend()
+            else:
+                ax.barh(labels, values, color=colors)
+            ax.xaxis.set_major_formatter(ticker.FuncFormatter(_format_currency))
+            if x_label:
+                ax.set_ylabel(x_label)  # Swapped for horizontal
+            if y_label:
+                ax.set_xlabel(y_label)
+
+        elif chart_type == "pie":
+            ax.pie(
+                values,
+                labels=labels,
+                colors=colors,
+                autopct="%1.1f%%",
+                startangle=90,
+            )
+            ax.axis("equal")
+
+        elif chart_type == "line":
+            ax.plot(labels, values, color=COLORS[0], marker="o", linewidth=2, label=y_column.replace("_", " ").title() if has_y2 else None)
+            if has_y2:
+                ax.plot(labels, values2, color=COLORS[1], marker="s", linewidth=2, label=y2_column.replace("_", " ").title())
+                ax.legend()
+            ax.yaxis.set_major_formatter(ticker.FuncFormatter(_format_currency))
+            if x_label:
+                ax.set_xlabel(x_label)
+            if y_label:
+                ax.set_ylabel(y_label)
+            plt.xticks(rotation=45, ha="right")
+
+        ax.set_title(title, fontsize=14, fontweight="bold", pad=15)
+        fig.tight_layout()
+
+        # Save to temp file
+        tmp = tempfile.NamedTemporaryFile(suffix=".png", prefix="cashy_chart_", delete=False)
+        fig.savefig(tmp.name, dpi=150, bbox_inches="tight")
+        plt.close(fig)
+
+        logger.info("[generate_chart] Saved chart to %s", tmp.name)
+
+        summary = f"{chart_type.replace('_', ' ').title()} chart with {len(labels)} data points"
+        if has_y2:
+            summary += f" comparing {y_column} vs {y2_column}"
+
+        return json.dumps({
+            "success": True,
+            "chart_path": tmp.name,
+            "chart_type": chart_type,
+            "data_points": len(labels),
+            "summary": summary,
+        })
+
+    except Exception as e:
+        logger.error("[generate_chart] Error: %s", e)
+        plt.close("all")
+        return json.dumps({"success": False, "error": str(e)})

src/tools/recent_transactions.py

@@ -0,0 +1,53 @@
+import json
+import logging
+from langchain_core.tools import tool
+from src.db.connection import get_connection
+
+logger = logging.getLogger("cashy.tools")
+
+
+@tool
+def get_recent_transactions(limit: int = 10) -> str:
+    """Get the most recent transactions. Returns date, description, amount, type, category, and account.
+    Transfers are shown as a single entry with from_account and to_account."""
+    logger.info("[get_recent_transactions] limit=%d", limit)
+    try:
+        with get_connection() as conn:
+            with conn.cursor() as cur:
+                # Get recent unique transactions (by transaction id)
+                # For transfers: collapse 2 entries into one row with from/to accounts
+                cur.execute(
+                    """
+                    SELECT t.id, t.transaction_date, t.description, t.transaction_type,
+                           t.total_amount,
+                           debit_a.name  AS from_account,
+                           credit_a.name AS to_account,
+                           c.name        AS category
+                    FROM transactions t
+                    LEFT JOIN transaction_entries debit_te
+                        ON debit_te.transaction_id = t.id AND debit_te.entry_type = 'debit'
+                    LEFT JOIN accounts debit_a
+                        ON debit_te.account_id = debit_a.id
+                    LEFT JOIN transaction_entries credit_te
+                        ON credit_te.transaction_id = t.id AND credit_te.entry_type = 'credit'
+                    LEFT JOIN accounts credit_a
+                        ON credit_te.account_id = credit_a.id
+                    LEFT JOIN categories c
+                        ON debit_te.category_id = c.id
+                    ORDER BY t.transaction_date DESC, t.id DESC
+                    LIMIT %s
+                    """,
+                    (limit,),
+                )
+                columns = [desc[0] for desc in cur.description]
+                rows = cur.fetchall()
+                results = [dict(zip(columns, row)) for row in rows]
+
+                logger.info("[get_recent_transactions] Returned %d transactions", len(results))
+                return json.dumps(
+                    {"success": True, "count": len(results), "transactions": results},
+                    default=str,
+                )
+    except Exception as e:
+        logger.error("[get_recent_transactions] Error: %s", e)
+        return json.dumps({"success": False, "error": str(e)})

src/tools/spending_by_category.py

@@ -0,0 +1,54 @@
+import json
+import logging
+from datetime import datetime
+from langchain_core.tools import tool
+from src.db.connection import get_connection
+
+logger = logging.getLogger("cashy.tools")
+
+
+@tool
+def get_spending_by_category(month: int = 0, year: int = 0) -> str:
+    """Get spending breakdown by category for a specific month/year.
+    Use month=0 and year=0 for current month."""
+    try:
+        current_month = datetime.now().month if month == 0 else month
+        current_year = datetime.now().year if year == 0 else year
+        logger.info("[get_spending_by_category] month=%d, year=%d", current_month, current_year)
+
+        with get_connection() as conn:
+            with conn.cursor() as cur:
+                cur.execute(
+                    """
+                    SELECT c.name as category,
+                           c.category_type,
+                           SUM(te.amount) as total
+                    FROM transaction_entries te
+                    JOIN categories c ON te.category_id = c.id
+                    JOIN transactions t ON te.transaction_id = t.id
+                    WHERE EXTRACT(MONTH FROM t.transaction_date) = %s
+                        AND EXTRACT(YEAR FROM t.transaction_date) = %s
+                        AND te.entry_type = 'debit'
+                        AND c.category_type = 'expense'
+                    GROUP BY c.name, c.category_type
+                    ORDER BY total DESC
+                    """,
+                    (current_month, current_year),
+                )
+                columns = [desc[0] for desc in cur.description]
+                rows = cur.fetchall()
+                results = [dict(zip(columns, row)) for row in rows]
+
+                logger.info("[get_spending_by_category] Returned %d categories", len(results))
+                return json.dumps(
+                    {
+                        "success": True,
+                        "month": current_month,
+                        "year": current_year,
+                        "spending": results,
+                    },
+                    default=str,
+                )
+    except Exception as e:
+        logger.error("[get_spending_by_category] Error: %s", e)
+        return json.dumps({"success": False, "error": str(e)})

src/tools/update_transaction.py

@@ -0,0 +1,157 @@
+import json
+import logging
+from datetime import datetime
+from langchain_core.tools import tool
+from langgraph.types import interrupt
+from src.db.connection import get_connection
+
+logger = logging.getLogger("cashy.tools")
+
+
+@tool
+def update_transaction(
+    transaction_id: int,
+    description: str = "",
+    amount: float = 0.0,
+    date: str = "",
+    category_name: str = "",
+    notes: str = "",
+) -> str:
+    """Update an existing transaction. Only provided (non-empty/non-zero) fields are changed.
+    Requires the transaction_id. The user will be asked to confirm before changes are applied."""
+    logger.info("[update_transaction] id=%d", transaction_id)
+
+    try:
+        with get_connection() as conn:
+            with conn.cursor() as cur:
+                # Fetch current transaction details for confirmation display
+                cur.execute(
+                    """
+                    SELECT t.id, t.transaction_date, t.description, t.transaction_type,
+                           t.total_amount, t.notes,
+                           a.name as account_name, c.name as category_name
+                    FROM transactions t
+                    JOIN transaction_entries te ON te.transaction_id = t.id
+                    JOIN accounts a ON te.account_id = a.id
+                    LEFT JOIN categories c ON te.category_id = c.id
+                    WHERE t.id = %s
+                    LIMIT 1
+                    """,
+                    (transaction_id,),
+                )
+                row = cur.fetchone()
+                if not row:
+                    return json.dumps({"success": False, "error": f"Transaction {transaction_id} not found"})
+
+                current = {
+                    "id": row[0],
+                    "date": str(row[1]),
+                    "description": row[2],
+                    "type": row[3],
+                    "amount": float(row[4]),
+                    "notes": row[5] or "",
+                    "account": row[6],
+                    "category": row[7] or "Uncategorized",
+                }
+
+                # Build changes summary
+                changes = {}
+                if description and description.strip():
+                    changes["description"] = description.strip()
+                if amount > 0:
+                    changes["amount"] = amount
+                if date and date.strip():
+                    try:
+                        datetime.strptime(date.strip(), "%Y-%m-%d")
+                        changes["date"] = date.strip()
+                    except ValueError:
+                        return json.dumps({"success": False, "error": "Invalid date format. Use YYYY-MM-DD"})
+                if notes and notes.strip():
+                    changes["notes"] = notes.strip()
+
+                # Resolve category if provided
+                new_category_id = None
+                if category_name and category_name.strip():
+                    cur.execute(
+                        "SELECT id, name FROM categories WHERE name ILIKE %s AND is_active = true",
+                        (f"%{category_name}%",),
+                    )
+                    cat = cur.fetchone()
+                    if cat:
+                        new_category_id = cat[0]
+                        changes["category"] = cat[1]
+                    else:
+                        return json.dumps({"success": False, "error": f"Category '{category_name}' not found"})
+
+                if not changes:
+                    return json.dumps({"success": False, "error": "No fields to update"})
+
+    except Exception as e:
+        logger.error("[update_transaction] Lookup error: %s", e)
+        return json.dumps({"success": False, "error": str(e)})
+
+    # --- Confirmation gate ---
+    confirmation = {
+        "action": "update_transaction",
+        "message": f"Update transaction #{transaction_id}?",
+        "current": current,
+        "changes": changes,
+    }
+    response = interrupt(confirmation)
+
+    if not response.get("approved"):
+        logger.info("[update_transaction] Cancelled by user")
+        return json.dumps({"success": False, "message": "Update cancelled by user"})
+
+    # --- Execute the update ---
+    try:
+        with get_connection() as conn:
+            with conn.cursor() as cur:
+                # Update transactions table
+                tx_updates = []
+                tx_params = []
+                if "description" in changes:
+                    tx_updates.append("description = %s")
+                    tx_params.append(changes["description"])
+                if "amount" in changes:
+                    tx_updates.append("total_amount = %s")
+                    tx_params.append(changes["amount"])
+                if "date" in changes:
+                    tx_updates.append("transaction_date = %s")
+                    tx_params.append(changes["date"])
+                if "notes" in changes:
+                    tx_updates.append("notes = %s")
+                    tx_params.append(changes["notes"])
+
+                if tx_updates:
+                    tx_params.append(transaction_id)
+                    cur.execute(
+                        f"UPDATE transactions SET {', '.join(tx_updates)} WHERE id = %s",
+                        tx_params,
+                    )
+
+                # Update transaction_entries if amount or category changed
+                if "amount" in changes:
+                    cur.execute(
+                        "UPDATE transaction_entries SET amount = %s WHERE transaction_id = %s",
+                        (changes["amount"], transaction_id),
+                    )
+                if new_category_id is not None:
+                    cur.execute(
+                        "UPDATE transaction_entries SET category_id = %s WHERE transaction_id = %s",
+                        (new_category_id, transaction_id),
+                    )
+
+                logger.info("[update_transaction] Updated txn_id=%d fields=%s", transaction_id, list(changes.keys()))
+                return json.dumps(
+                    {
+                        "success": True,
+                        "transaction_id": transaction_id,
+                        "message": f"Transaction #{transaction_id} updated",
+                        "changes": changes,
+                    },
+                    default=str,
+                )
+    except Exception as e:
+        logger.error("[update_transaction] Error: %s", e)
+        return json.dumps({"success": False, "error": str(e)})

src/ui.py

@@ -0,0 +1,553 @@
+import json
+import uuid
+import time
+import logging
+import gradio as gr
+from langchain_core.messages import HumanMessage
+from langgraph.types import Command
+from src.config import settings
+from src.agent.nodes import reset_model
+from src.db.connection import get_connection
+
+logger = logging.getLogger("cashy.ui")
+
+
+def list_threads():
+    """Get all thread_ids from the checkpoints table, most recent first."""
+    try:
+        with get_connection() as conn:
+            with conn.cursor() as cur:
+                cur.execute("""
+                    SELECT thread_id, MAX(checkpoint_id) AS latest
+                    FROM checkpoints
+                    GROUP BY thread_id
+                    ORDER BY latest DESC
+                """)
+                return [row[0] for row in cur.fetchall()]
+    except Exception as e:
+        logger.warning("Could not list threads: %s", e)
+        return []
+
+
+def load_thread_history(agent, thread_id):
+    """Load messages from a thread and convert to Gradio chatbot format."""
+    config = {"configurable": {"thread_id": thread_id}}
+    state = agent.get_state(config)
+    messages = state.values.get("messages", [])
+
+    history = []
+    for msg in messages:
+        if msg.type == "human":
+            history.append({"role": "user", "content": msg.content})
+        elif msg.type == "ai" and msg.content:
+            history.append({"role": "assistant", "content": msg.content})
+        elif msg.type == "tool":
+            try:
+                data = json.loads(msg.content)
+                if isinstance(data, dict) and "chart_path" in data:
+                    history.append({"role": "assistant", "content": {"path": data["chart_path"]}})
+            except (json.JSONDecodeError, TypeError):
+                pass
+    return history
+
+
+def get_thread_title(agent, thread_id):
+    """Extract first user message as thread title (truncated to 50 chars)."""
+    config = {"configurable": {"thread_id": thread_id}}
+    try:
+        state = agent.get_state(config)
+        for msg in state.values.get("messages", []):
+            if msg.type == "human":
+                title = msg.content[:50]
+                return title + "..." if len(msg.content) > 50 else title
+    except Exception:
+        pass
+    return thread_id[:12]
+
+
+def get_thread_choices(agent, min_user_messages=2):
+    """Build dropdown choices as (title, thread_id) tuples.
+
+    Only includes threads with at least min_user_messages user messages,
+    filtering out orphan single-exchange threads.
+    """
+    threads = list_threads()
+    choices = []
+    for tid in threads:
+        config = {"configurable": {"thread_id": tid}}
+        try:
+            state = agent.get_state(config)
+            messages = state.values.get("messages", [])
+            user_msgs = [m for m in messages if m.type == "human"]
+            if len(user_msgs) < min_user_messages:
+                continue
+            first_msg = user_msgs[0].content[:50]
+            title = first_msg + "..." if len(user_msgs[0].content) > 50 else first_msg
+            choices.append((title, tid))
+        except Exception:
+            continue
+    return choices
+
+
+def format_confirmation(interrupt_data):
+    """Format an interrupt payload as a user-friendly confirmation message."""
+    action = interrupt_data.get("action", "unknown")
+    message = interrupt_data.get("message", "Confirm this action?")
+
+    # Build a readable action label
+    action_labels = {
+        "create_transaction": "Create Transaction",
+        "update_transaction": "Update Transaction",
+        "delete_transaction": "Delete Transaction",
+    }
+    label = action_labels.get(action, action.replace("_", " ").title())
+
+    lines = [f"**Confirm: {label}**\n"]
+
+    # Show details as a table
+    details = interrupt_data.get("details", {})
+    if details:
+        lines.append("| Field | Value |")
+        lines.append("|-------|-------|")
+        for key, value in details.items():
+            display_key = key.replace("_", " ").title()
+            if key == "amount":
+                display_value = f"${value:,.2f}"
+            else:
+                display_value = str(value)
+            lines.append(f"| {display_key} | {display_value} |")
+        lines.append("")
+
+    # Show changes for update operations
+    changes = interrupt_data.get("changes", {})
+    if changes:
+        lines.append("**Changes:**\n")
+        lines.append("| Field | New Value |")
+        lines.append("|-------|-----------|")
+        for key, value in changes.items():
+            display_key = key.replace("_", " ").title()
+            if key == "amount":
+                display_value = f"${value:,.2f}"
+            else:
+                display_value = str(value)
+            lines.append(f"| {display_key} | {display_value} |")
+        lines.append("")
+
+    # Show current values for update operations
+    current = interrupt_data.get("current", {})
+    if current:
+        lines.append("**Current values:**\n")
+        lines.append("| Field | Value |")
+        lines.append("|-------|-------|")
+        for key, value in current.items():
+            display_key = key.replace("_", " ").title()
+            if key == "amount":
+                display_value = f"${value:,.2f}"
+            else:
+                display_value = str(value)
+            lines.append(f"| {display_key} | {display_value} |")
+        lines.append("")
+
+    lines.append("Reply **yes** to confirm or **no** to cancel.")
+
+    return "\n".join(lines)
+
+
+WELCOME_MESSAGE_DEMO = """\
+Hi! I'm **Cashy**, your AI financial advisor.
+
+I'm connected to a demo database with **4 months of financial data** for a US-based freelance web developer:
+
+- **11 accounts** — Chase, PayPal, Stripe, Wise, Marcus, Fidelity, credit cards, and cash
+- **233 transactions** — client invoices, business expenses, personal spending, transfers
+- **20 budgets** — monthly spending limits across 35 categories
+
+**Ready to go** with the free tier, or switch to your own LLM provider in the sidebar.
+
+Ask me anything about your finances. Here are some ideas:
+
+1. **"What accounts do I have?"** — See all accounts and balances
+2. **"How much did I spend this month?"** — Spending breakdown by category
+3. **"How much did I earn from clients in January?"** — Income tracking
+4. **"Am I over budget on anything?"** — Budget vs. actual comparison
+5. **"Show me my last 10 transactions"** — Recent transaction history
+"""
+
+WELCOME_MESSAGE_PERSONAL = """\
+Hi! I'm **Cashy**, your AI financial advisor.
+
+I'm connected to your personal financial database. Ask me anything about your accounts, transactions, spending, or budgets.
+
+Here are some things I can help with:
+
+1. **"What accounts do I have?"** — See all accounts and balances
+2. **"How much did I spend this month?"** — Spending breakdown by category
+3. **"Show me my last 10 transactions"** — Recent transaction history
+4. **"Am I over budget on anything?"** — Budget vs. actual comparison
+5. **"Show me a chart of my spending"** — Visual spending analysis
+"""
+
+PROVIDERS = ["free-tier", "openai", "anthropic", "google", "huggingface"]
+
+DEFAULT_MODELS = {
+    "free-tier": "Qwen/Qwen2.5-7B-Instruct",
+    "openai": "gpt-5-mini",
+    "anthropic": "claude-sonnet-4-20250514",
+    "google": "gemini-2.5-flash",
+    "huggingface": "meta-llama/Llama-3.3-70B-Instruct",
+}
+
+HF_INFERENCE_PROVIDERS = [
+    "cerebras",
+    "cohere",
+    "featherless-ai",
+    "fireworks-ai",
+    "groq",
+    "hf-inference",
+    "hyperbolic",
+    "nebius",
+    "novita",
+    "nscale",
+    "ovhcloud",
+    "sambanova",
+    "scaleway",
+    "together",
+]
+
+
+def create_ui(agent):
+    """Create the Gradio chat UI with compact reference sidebar."""
+
+    current_provider = settings.resolved_provider or "openai"
+    has_provider = settings.resolved_provider is not None
+    is_free = current_provider == "free-tier"
+    is_demo = settings.app_mode == "demo"
+    mode_label = "Demo" if is_demo else "Personal"
+    welcome_text = WELCOME_MESSAGE_DEMO if is_demo else WELCOME_MESSAGE_PERSONAL
+
+    FREE_TIER_DISCLAIMER = (
+        "\n\n---\n*Free tier uses a lightweight open-source model. "
+        "For better results, switch to OpenAI, Anthropic, or Google in the sidebar.*"
+    )
+
+    def respond(message, history, thread_id, pending):
+        config = {"configurable": {"thread_id": thread_id}}
+
+        logger.info(">>> User [thread=%s]: %s", thread_id[:8], message)
+        start = time.time()
+
+        try:
+            # --- Resume from interrupt (user confirming/rejecting) ---
+            if pending:
+                approved = message.strip().lower() in ("yes", "approve", "confirm", "y")
+                logger.info("Interrupt response: %s", "approved" if approved else "rejected")
+
+                result = agent.invoke(Command(resume={"approved": approved}), config)
+
+                response = result["messages"][-1].content
+                elapsed = time.time() - start
+                logger.info("<<< Response [%.1fs]: %s", elapsed, response[:120])
+
+                if settings.resolved_provider == "free-tier":
+                    response += FREE_TIER_DISCLAIMER
+                history.append({"role": "user", "content": message})
+                history.append({"role": "assistant", "content": response})
+                return "", history, thread_id, False
+
+            # --- Normal flow ---
+            # Count existing messages so we only scan new ones for charts
+            state = agent.get_state(config)
+            prev_count = len(state.values.get("messages", []))
+
+            result = agent.invoke(
+                {"messages": [HumanMessage(content=message)]},
+                config,
+            )
+
+            # --- Check for interrupt (write operation needs confirmation) ---
+            if "__interrupt__" in result:
+                interrupt_data = result["__interrupt__"][0].value
+                confirmation_msg = format_confirmation(interrupt_data)
+                elapsed = time.time() - start
+                logger.info("<<< Interrupt [%.1fs]: %s", elapsed, interrupt_data.get("action", "unknown"))
+
+                history.append({"role": "user", "content": message})
+                history.append({"role": "assistant", "content": confirmation_msg})
+                return "", history, thread_id, True
+
+            # --- Normal response (no interrupt) ---
+            response = result["messages"][-1].content
+            elapsed = time.time() - start
+            logger.info("<<< Response [%.1fs]: %s", elapsed, response[:120])
+
+            # Scan only NEW messages for chart images (skip prior history)
+            chart_paths = []
+            for msg in result["messages"][prev_count:]:
+                if hasattr(msg, "type") and msg.type == "tool":
+                    try:
+                        data = json.loads(msg.content)
+                        if isinstance(data, dict) and "chart_path" in data:
+                            chart_paths.append(data["chart_path"])
+                    except (json.JSONDecodeError, TypeError):
+                        pass
+
+            if settings.resolved_provider == "free-tier":
+                response += FREE_TIER_DISCLAIMER
+            history.append({"role": "user", "content": message})
+            history.append({"role": "assistant", "content": response})
+            for path in chart_paths:
+                history.append({"role": "assistant", "content": {"path": path}})
+
+            return "", history, thread_id, False
+
+        except Exception as e:
+            logger.error("<<< Error: %s", e)
+            error_str = str(e).lower()
+            if "ssl" in error_str or "connection" in error_str and "closed" in error_str:
+                msg = (
+                    "The database connection was lost (the cloud database likely went to sleep). "
+                    "Please try again in a few seconds -- it should reconnect automatically. "
+                    "If the issue persists, restart the Space from Settings."
+                )
+            else:
+                msg = f"**Error:** {e}"
+            history.append({"role": "user", "content": message})
+            history.append({"role": "assistant", "content": msg})
+            return "", history, thread_id, False
+
+    def switch_provider(provider):
+        settings.llm_provider = provider
+        settings.model_name = ""  # reset to default for new provider
+        reset_model()
+        model = DEFAULT_MODELS.get(provider, "default")
+        is_free = provider == "free-tier"
+        is_hf = provider == "huggingface"
+        show_byok = not is_free  # free-tier hides API key, model, HF provider
+        logger.info("Provider switched to: %s (%s)", provider, model)
+        if is_free:
+            status = f"Using **Free Tier** ({model}) -- no API key needed"
+        else:
+            status = f"Switched to **{provider.capitalize()}** ({model})"
+        return (
+            status,
+            gr.update(visible=show_byok, value=""),
+            gr.update(visible=show_byok, placeholder=f"Default: {model}", value=""),
+            gr.update(visible=is_hf),
+            gr.update(visible=show_byok),
+        )
+
+    def set_api_key(provider, api_key, model_name, hf_provider):
+        key = api_key.strip()
+        if not key:
+            return "No key entered."
+        key_fields = {
+            "openai": "openai_api_key",
+            "anthropic": "anthropic_api_key",
+            "google": "google_api_key",
+            "huggingface": "hf_token",
+        }
+        field = key_fields.get(provider)
+        if not field:
+            return f"Unknown provider: {provider}"
+        setattr(settings, field, key)
+        settings.llm_provider = provider
+        if model_name.strip():
+            settings.model_name = model_name.strip()
+        if provider == "huggingface" and hf_provider:
+            settings.hf_inference_provider = hf_provider
+        reset_model()
+        model = settings.model_name or DEFAULT_MODELS.get(provider, "default")
+        logger.info("API key set for provider: %s (%s)", provider, model)
+        return f"API key saved. Using **{provider.capitalize()}** ({model})."
+
+    def set_model(provider, model_name):
+        name = model_name.strip()
+        settings.model_name = name
+        reset_model()
+        model = name or DEFAULT_MODELS.get(provider, "default")
+        logger.info("Model changed to: %s", model)
+        return f"Model set to **{model}**."
+
+    def set_hf_provider(hf_provider):
+        settings.hf_inference_provider = hf_provider
+        reset_model()
+        logger.info("HF inference provider changed to: %s", hf_provider)
+        return f"Inference provider set to **{hf_provider}**."
+
+    welcome = [{"role": "assistant", "content": welcome_text}]
+
+    if is_demo:
+        theme = gr.themes.Glass(primary_hue="indigo")
+    else:
+        theme = gr.themes.Default()
+
+    with gr.Blocks(title="Cashy - AI Financial Advisor") as demo:
+        gr.Markdown("# Cashy — AI Financial Advisor")
+        session_thread_id = gr.State(value=lambda: str(uuid.uuid4()))
+        pending_interrupt = gr.State(value=False)
+
+        with gr.Row():
+            with gr.Column(scale=3):
+                chatbot = gr.Chatbot(
+                    value=welcome,
+                    height=600,
+                    buttons=["copy"],
+                )
+                with gr.Row():
+                    msg = gr.Textbox(
+                        placeholder="Ask about your finances...",
+                        show_label=False,
+                        scale=9,
+                    )
+                    submit_btn = gr.Button("Send", variant="primary", scale=1)
+
+            with gr.Column(scale=1, min_width=250):
+                new_chat_btn = gr.Button("+ New Chat", variant="secondary")
+
+                if not is_demo:
+                    with gr.Accordion("Chat History", open=False):
+                        thread_dropdown = gr.Dropdown(
+                            choices=[],
+                            label="Previous chats",
+                            interactive=True,
+                        )
+                        load_btn = gr.Button("Load Chat")
+
+                gr.Markdown(f"**Mode:** {mode_label}")
+
+                gr.Markdown("---")
+
+                if is_demo:
+                    gr.Markdown(
+                        "**Demo Data** · Oct 2025 – Jan 2026 · USD\n\n"
+                        "11 accounts · 233 transactions · 20 budgets"
+                    )
+                    gr.Markdown("---")
+
+                gr.Markdown(
+                    "**Capabilities**\n\n"
+                    "- Check account balances\n"
+                    "- Analyze spending by category\n"
+                    "- Search transaction history\n"
+                    "- Compare budgets vs. actual\n"
+                    "- Create, update, delete transactions\n"
+                    "- Run custom SQL queries"
+                )
+
+                gr.Markdown("---")
+
+                if is_demo:
+                    gr.Markdown(
+                        "**Try asking**\n\n"
+                        '*"What\'s the balance on Chase Business?"*\n\n'
+                        '*"Am I over budget on anything?"*\n\n'
+                        '*"I need a $1,500 laptop -- can I afford it?"*\n\n'
+                        '*"Show me a pie chart of my spending"*\n\n'
+                        '*"Chart my budget vs actual for January"*'
+                    )
+                else:
+                    gr.Markdown(
+                        "**Try asking**\n\n"
+                        '*"What accounts do I have?"*\n\n'
+                        '*"How much did I spend this month?"*\n\n'
+                        '*"Show me a chart of my spending"*'
+                    )
+
+                gr.Markdown("---")
+
+                provider_dropdown = gr.Dropdown(
+                    choices=PROVIDERS,
+                    value=current_provider,
+                    label="LLM Provider",
+                )
+                with gr.Row():
+                    api_key_input = gr.Textbox(
+                        label="API Key",
+                        placeholder="Paste your API key here...",
+                        type="password",
+                        scale=4,
+                        visible=not is_free,
+                    )
+                    save_key_btn = gr.Button("Save", variant="primary", scale=1, visible=not is_free)
+                model_name_input = gr.Textbox(
+                    label="Model Name (optional)",
+                    placeholder=f"Default: {DEFAULT_MODELS.get(current_provider, '')}",
+                    value="",
+                    visible=not is_free,
+                )
+                hf_provider_dropdown = gr.Dropdown(
+                    choices=HF_INFERENCE_PROVIDERS,
+                    value=settings.hf_inference_provider,
+                    label="Inference Provider",
+                    visible=current_provider == "huggingface",
+                )
+                if is_free:
+                    status_text = f"Using **Free Tier** ({DEFAULT_MODELS['free-tier']}) -- no API key needed"
+                elif has_provider:
+                    status_text = f"Using **{current_provider.capitalize()}** ({DEFAULT_MODELS.get(current_provider, 'default')})"
+                else:
+                    status_text = "No API key configured -- select a provider and enter one above"
+                provider_status = gr.Markdown(status_text)
+
+        # --- Event handlers ---
+
+        # Chat events (now include pending_interrupt state)
+        chat_inputs = [msg, chatbot, session_thread_id, pending_interrupt]
+        chat_outputs = [msg, chatbot, session_thread_id, pending_interrupt]
+
+        if is_demo:
+            def new_chat_demo():
+                new_id = str(uuid.uuid4())
+                logger.info("New chat started [thread=%s]", new_id[:8])
+                return new_id, welcome, "", False
+
+            msg.submit(respond, chat_inputs, chat_outputs)
+            submit_btn.click(respond, chat_inputs, chat_outputs)
+            new_chat_btn.click(
+                new_chat_demo, [], [session_thread_id, chatbot, msg, pending_interrupt]
+            )
+        else:
+            def new_chat():
+                new_id = str(uuid.uuid4())
+                choices = get_thread_choices(agent)
+                logger.info("New chat started [thread=%s]", new_id[:8])
+                return new_id, welcome, "", gr.update(choices=choices), False
+
+            def load_thread(selected_thread_id):
+                if not selected_thread_id:
+                    return gr.update(), gr.update(), False
+                history = load_thread_history(agent, selected_thread_id)
+                logger.info("Loaded thread %s (%d messages)", selected_thread_id[:8], len(history))
+                return selected_thread_id, history, False
+
+            def refresh_threads():
+                choices = get_thread_choices(agent)
+                return gr.update(choices=choices)
+
+            msg.submit(respond, chat_inputs, chat_outputs).then(
+                refresh_threads, [], [thread_dropdown]
+            )
+            submit_btn.click(respond, chat_inputs, chat_outputs).then(
+                refresh_threads, [], [thread_dropdown]
+            )
+            new_chat_btn.click(
+                new_chat, [], [session_thread_id, chatbot, msg, thread_dropdown, pending_interrupt]
+            )
+            load_btn.click(
+                load_thread, [thread_dropdown], [session_thread_id, chatbot, pending_interrupt]
+            )
+        provider_dropdown.change(
+            switch_provider, [provider_dropdown],
+            [provider_status, api_key_input, model_name_input, hf_provider_dropdown, save_key_btn],
+        )
+        api_key_inputs = [provider_dropdown, api_key_input, model_name_input, hf_provider_dropdown]
+        api_key_input.submit(set_api_key, api_key_inputs, [provider_status])
+        save_key_btn.click(set_api_key, api_key_inputs, [provider_status])
+        model_name_input.submit(set_model, [provider_dropdown, model_name_input], [provider_status])
+        hf_provider_dropdown.change(set_hf_provider, [hf_provider_dropdown], [provider_status])
+
+        # Populate thread list on page load (personal mode only)
+        if not is_demo:
+            demo.load(refresh_threads, [], [thread_dropdown])
+
+    return demo, theme