Legacy AI Financial Advisory

An open-source AI-powered financial advisory application that simulates a "boardroom" of AI financial advisors. Built with privacy and local-first principles, this system uses LangGraph for multi-agent orchestration, with each advisor having a unique persona configured via YAML files.

Features

• Multi-Agent AI Advisory: Simulate debates between different AI financial personas
• Privacy-First: Designed to run entirely locally via Docker Compose
• Actual Budget Integration: Direct SQLite access to your transaction history (read-only)
• PII Protection: Automatic scrubbing of sensitive information
• Extensible: Add new advisor personas without touching code
• Financial Precision: Uses Decimal type for all monetary calculations

Tech Stack

Backend

• FastAPI: High-performance Python API
• LangGraph: Multi-agent workflow orchestration
• SQLAlchemy: Database ORM with pgvector support
• Pydantic: Configuration validation and data modeling
• Docker: Containerized deployment

Frontend

• Next.js 16: React App Router
• React 19: Latest React features
• TypeScript: Type-safe development
• Tailwind CSS v4: Modern styling

Database

• PostgreSQL with pgvector: Main database (runs in Docker)
• Vector embeddings: Semantic search for transaction patterns
• SQLite: Actual Budget integration (read-only)

Quick Start

Prerequisites

• Docker and Docker Compose
• OpenAI API key OR Anthropic API key (for AI advisors)
• (Optional) Actual Budget instance for transaction sync

Installation

1. Clone the repository:

   git clone <your-repo-url>
   cd legacy-ai

2. Set up environment variables:

   cp .env.example .env
   # Edit .env with your actual values

3. Start the backend:

   docker-compose up -d

4. Verify it's running:

   curl http://localhost:8000/
   # Should return: {"status":"healthy","version":"0.1.0","actual_budget_enabled":true}

5. Access API documentation:

   • Swagger UI: http://localhost:8000/docs
   • ReDoc: http://localhost:8000/redoc

Frontend (Development)

The frontend runs locally outside of Docker for now:

cd frontend
npm install
npm run dev
# Access at http://localhost:3000

Configuration

Environment Variables

Copy .env.example to .env and configure:

Required:

• OPENAI_API_KEY or ANTHROPIC_API_KEY: For AI advisors
• DB_PASSWORD: PostgreSQL database password (change from default!)

Optional:

• ACTUAL_BUDGET_DB_PATH: Path to Actual Budget SQLite database (recommended)
• ACTUAL_BUDGET_URL + ACTUAL_BUDGET_PASSWORD: For remote Actual Budget API
• CORS_ORIGINS: Allowed frontend origins (default: localhost:3000)
• DISABLE_LEGAL_DISCLAIMERS: Set to true for personal use (default: false)

Actual Budget Integration

This project can read directly from your Actual Budget database. See ACTUAL_BUDGET_SETUP.md for detailed instructions.

For local development with sample data:

A test database with 152 realistic transactions is included for development:

# Generate fresh sample data (optional - already included)
python3 create_sample_actual_budget_db.py

# The docker-compose.yml is already configured to use it
# Just make sure your .env has:
ACTUAL_BUDGET_DB_PATH=/actual-budget/server-files/default.sqlite

# Test it:
curl -X POST http://localhost:8000/ingest/sync
# Returns: {"success":true,"transactions_count":152,"message":"..."}

The sample data includes:

• 6 months of transaction history
• Recurring bills (rent, insurance, subscriptions)
• Random daily purchases (groceries, gas, coffee, etc.)
• Income (bi-weekly salary + occasional freelance)
• Realistic amounts and categories

Quick setup if you already have Actual Budget running:

1. Find your volume:

   docker volume ls | grep actual

2. Update docker-compose.yml:

   backend:
     volumes:
       - your-actual-budget-volume:/actual-budget:ro
   
   volumes:
     your-actual-budget-volume:
       external: true

3. Set in .env:

   ACTUAL_BUDGET_DB_PATH=/actual-budget/server-files/default.sqlite

API Endpoints

Health & Status

• GET / - Health check and feature status

Data Ingestion (Phase 1)

• POST /ingest/upload - Upload CSV file with transactions
• POST /ingest/sync - Sync from Actual Budget (SQLite or API)

Multi-Agent Chat (Phase 2) ✨ NEW

• POST /api/chat/start - Start new conversation with advisory board
• GET /api/chat/{thread_id}/stream - Stream conversation updates (SSE)
• POST /api/chat/{thread_id}/resume - Resume with human feedback
• GET /api/chat/{thread_id}/history - Get conversation history

Example: Upload CSV

curl -X POST http://localhost:8000/ingest/upload \
  -F "file=@transactions.csv" \
  -F "date_column=date" \
  -F "amount_column=amount" \
  -F "payee_column=payee" \
  -F "category_column=category"

CSV Format:

date,amount,payee,category
2024-01-15,-45.99,Grocery Store,Food
2024-01-16,2500.00,Salary,Income

Example: Sync from Actual Budget

curl -X POST http://localhost:8000/ingest/sync

Project Structure

/backend
  /app
    /agents       # LangGraph multi-agent workflows ✨ NEW (Phase 2)
    /api          # FastAPI routes
      chat.py     # Multi-agent chat endpoints ✨ NEW
    /core         # Configuration, security, logging
      advisor_loader.py  # Dynamic YAML configuration ✨ NEW
      disclaimers.py     # Legal disclaimer system ✨ NEW
    /models       # SQLAlchemy ORM models ✨ NEW
    /services     # Data ingestion adapters (CSV, Actual Budget)
  /config         # Default YAMLs (advisors.yaml ✨ NEW)
  /migrations     # Database schema (init.sql ✨ NEW)
  main.py         # FastAPI entrypoint
  Dockerfile
  requirements.txt

/frontend         # Next.js application
  /src
    /app          # App Router pages
    /components   # React components (coming soon)

/documentation    # Project specs and PRDs
docker-compose.yml  # Includes PostgreSQL with pgvector ✨ UPDATED
.env.example        # Added Phase 2 configuration ✨ UPDATED
CLAUDE.md           # Instructions for Claude Code

Development

Backend Development

The backend code is mounted as a volume for hot-reloading:

# Make changes to backend/app/**/*.py
# Container automatically restarts with changes
docker-compose logs -f backend

Adding New Data Sources

Extend the TransactionSource abstract base class:

from app.services.ingestion import TransactionSource, StandardTransaction

class MyCustomSource(TransactionSource):
    def fetch_transactions(self, start_date=None, end_date=None):
        # Your implementation
        return [StandardTransaction(...), ...]

Adding New Advisor Personas

Edit backend/config/advisors.yaml:

advisors:
  - id: conservative_advisor
    name: "Conservative Advisor"
    role: "Risk Minimization"
    icon: "shield"
    system_prompt: "You are a conservative financial advisor..."
    model_config:
      provider: "openai"
      model_name: "gpt-4"
      temperature: 0.3

Deployment

Production Deployment

1. Update docker-compose.yml (remove development volume mount):

   backend:
     volumes:
       # - ./backend:/app  # Comment this out for production
       - your-actual-budget-volume:/actual-budget:ro

2. Build and deploy:

   docker-compose build
   docker-compose up -d

3. Verify:

   docker-compose ps
   curl http://localhost:8000/

Server with Existing Actual Budget

If deploying to a server where Actual Budget is already running:

1. Identify the Actual Budget volume name
2. Add it as an external volume in docker-compose.yml
3. Set ACTUAL_BUDGET_DB_PATH in .env
4. Deploy normally

See ACTUAL_BUDGET_SETUP.md for detailed instructions.

Security & Privacy

• No Hardcoded Secrets: All API keys loaded from .env
• Read-Only Actual Budget Access: Cannot modify your budget data
• PII Scrubbing: Automatically redacts account numbers, SSNs, etc.
• Financial Precision: Decimal type prevents floating-point errors
• Local-First: Default deployment is localhost via Docker
• Open Source: Fully auditable code

Roadmap

Phase 1 ✅ COMPLETE

• Backend configuration system
• Data ingestion (CSV, Actual Budget SQLite)
• PII scrubbing
• Docker deployment

Phase 2 ✅ COMPLETE

• PostgreSQL with pgvector in Docker
• LangGraph multi-agent system
• AI advisor orchestration (4 advisors + chairman)
• Dynamic advisor loading from YAML
• SSE streaming API
• Legal disclaimer system (opt-out)
• Database models and migrations
• Human-in-the-loop support

Phase 3 (Next)

• Next.js frontend
• Real-time agent message display
• Interactive plan refinement
• Transaction embedding pipeline
• Financial summary calculations

Contributing

This is an open-source project. Contributions are welcome!

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Issues: GitHub Issues
• Documentation: See /documentation folder for specs and PRDs

Acknowledgments

• Built with FastAPI
• Multi-agent orchestration via LangGraph
• Integrates with Actual Budget
• Inspired by the concept of AI advisory boards

---

Note: This project is under active development.

• ✅ Phase 1 & 2 Complete: Backend with multi-agent AI advisory system is functional
• 🚧 Phase 3 In Progress: Frontend development coming next

Try it out with docker-compose up and explore the API at http://localhost:8000/docs!