Liquidity

An AI-powered personal finance platform that optimizes budget allocations through natural language conversation. Users describe financial goals in plain English; a constraint solver finds the mathematically optimal plan.

What Makes This Different

A neuro-symbolic architecture that is user friendly and flexible while remaining 100% accurate

1. An LLM that understands intent — Claude extracts structured constraints from natural language ("I want to save $1000/mo and keep dining under $300")
2. A constraint solver that finds optimal plans — OR-Tools CP-SAT solves the resulting integer linear program, maximizing savings while respecting every constraint
3. Simulated banking data — Capital One's Nessie API provides actual bills, deposits, and transaction history as hard constraints

The result: a system where you talk about your budget and get back a mathematically optimal allocation.

Features

1. BudgetAgent — Claude extracts constraints via tool calling (e.g. "I want a $2000 watch" → add_user_constraint({category: "watch", op: ">=", amount: 2000, type: "hard"}))
2. Constraint Assembly — Merges AI-extracted + Nessie bank data + user-edited constraints, sanitizes categories into valid solver identifiers
3. OR-Tools CP-SAT Solver — Solves the integer linear program; if infeasible, iteratively drops lowest-priority soft constraints until a solution is found
4. Recommendations Engine — Math-computed health metrics (Housing Ratio, Savings Rate, 50/30/20 Split, Emergency Fund) directly from solver output
5. ExplainerAgent — Translates solver output into plain-English advice

Key Design Decisions

LLM as constraint extractor The system explicitly forbids LLMs from doing arithmetic. Its only job is to call add_user_constraint with structured JSON. All math runs through OR-Tools, which provides optimal solutions.

Iterative soft-constraint relaxation. When a plan is infeasible, the solver drops the lowest-priority soft constraint and retries, repeating until a feasible solution is found or no soft constraints remain. Users see exactly which constraints were relaxed and why.

Recommendations are computed, not generated. Financial health metrics (Housing Ratio, 50/30/20 compliance, Emergency Fund timeline) are calculated directly from solver output using threshold-based rules. This eliminates LLM hallucination for numerical advice.

Dual-agent separation of concerns. The BudgetAgent uses tool calling to extract constraints. The ExplainerAgent uses pure text generation to narrate results.

Tech Stack

Layer	Technology
Frontend	Next.js 16, React 19, TypeScript, Tailwind CSS 3, Shadcn/ui
Visualization	Recharts (donut, bar), react-resizable-panels
Backend	FastAPI, Pydantic, Uvicorn
AI	Anthropic Claude (via Dedalus Labs SDK), tool use pattern
Solver	Google OR-Tools CP-SAT (integer linear programming)
Banking	Capital One Nessie API (accounts, bills, deposits, purchases)
Auth	Supabase (JWT, user-to-bank-customer mapping)

Project Structure

Liquidity/
├── backend/
│   └── app/
│       ├── main.py              # FastAPI routes (11 endpoints)
│       ├── agent.py             # BudgetAgent — constraint extraction via Claude tool use
│       ├── explainer_agent.py   # ExplainerAgent — plain-English result narration
│       ├── solver.py            # OR-Tools CP-SAT wrapper + iterative relaxation
│       ├── nessie_client.py     # Capital One Nessie banking API client
│       ├── supabase_client.py   # Auth + user-bank mapping
│       └── models.py           # Pydantic request/response schemas
├── frontend/
│   ├── app/
│   │   ├── page.tsx             # Dashboard — account balances, spending trends
│   │   └── chat/page.tsx        # AI Copilot — split-pane budget optimizer
│   ├── components/
│   │   ├── chat/
│   │   │   ├── command-center.tsx      # Left pane: budget report + constraints + comparison
│   │   │   ├── copilot-chat.tsx        # Right pane: conversational constraint entry
│   │   │   ├── budget-report.tsx       # Allocation charts, bars, recommendations
│   │   │   └── scenario-comparison.tsx # Before/after delta visualization
│   │   ├── dashboard/           # Stat cards, charts, transaction list
│   │   └── ui/                  # Shadcn/ui primitives
│   └── lib/
│       ├── api.ts               # Type-safe API client
│       └── supabase.ts          # Supabase auth client
└── README.md

Getting Started

Prerequisites

• Node.js 18+
• Python 3.8+
• API keys: Nessie, Anthropic (or Dedalus Labs), Supabase

Setup

1. Install dependencies:

cd backend && python3 -m venv venv && source venv/bin/activate && pip install -r requirements.txt
cd frontend && npm install

2. Configure environment variables in backend/.env and frontend/.env.local

3. Run both servers:

./start-all.sh    # starts backend (:8000) + frontend (:3000)
./stop-all.sh     # kills both servers