---
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