# 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