Complete Documentation

Clone the repository:
git clone https://github.com/virattt/ai-hedge-fund.git cd ai-hedge-fund
Set up environment variables:
cp .env.example .env
Edit `.env` file and add at least one LLM API key (see API Keys section)
Install dependencies:
# Install Poetry (if not installed) curl -sSL https://install.python-poetry.org | python3 - # Install Python dependencies poetry install # Install frontend dependencies cd app/frontend npm install

Running the Application

Option 1: Using the Convenience Script (Easiest)

cd app
./run.sh  # Mac/Linux
# or
run.bat   # Windows

Option 2: Manual Start

Terminal 1 - Backend:

cd app/backend
poetry run uvicorn app.backend.main:app --reload --host 127.0.0.1 --port 8000

Terminal 2 - Frontend:

cd app/frontend
npm run dev

✅ Access Points:

Frontend: http://localhost:5173
API Docs: http://localhost:8000/docs
Backend API: http://localhost:8000

🚀 Getting Started

First Steps

Open the web interface at http://localhost:5173
Configure API Keys (Settings → API Keys) - see API Keys section
Select a theme (Settings → Theme)
Build your first flow (Main canvas)

Understanding the Interface

Left Sidebar

Agent library and flow management. Drag agents onto the canvas.

Center Canvas

Visual flow builder. Drag-and-drop agents and connect them.

Right Panel

Node configuration. Set tickers, models, and parameters.

Bottom Panel

Execution results and logs. See real-time progress.

💡 Tip: For a detailed walkthrough, check out our Complete User Guide.

🔑 API Keys Management

Supported Providers

AI Hedge Fund supports multiple LLM providers:

OpenAI

GPT-4o (recommended)
GPT-4o-mini (affordable)
GPT-4

Groq

DeepSeek
Llama 3
Mixtral

Others

Anthropic (Claude)
Ollama (free, local)
Google Gemini
DeepSeek
xAI (Grok)
OpenRouter

How to Add API Keys

Go to Settings → API Keys in the web interface
Click "Add API Key"
Select your provider
Enter your API key
Click "Save"

💡 Recommendation: Start with Ollama (free) or GPT-4o-mini (very affordable) for testing. See our pricing page for cost estimates.

⚠️ Security Note: API keys are stored in your local database. Never commit API keys to version control. Use `.env` files and add them to `.gitignore`.

🤖 Understanding AI Agents

AI Hedge Fund includes 18 different AI agents, each with unique investment strategies. See our complete agents page for details on each agent.

Agent Categories

Value Investing

Warren Buffett, Charlie Munger, Ben Graham, Michael Burry

Focus on undervalued companies with strong fundamentals.

Growth Investing

Peter Lynch, Phil Fisher, Cathie Wood, Mohnish Pabrai

Seek companies with high growth potential.

Specialized

Bill Ackman, Stanley Druckenmiller, Rakesh Jhunjhunwala, Aswath Damodaran

Unique approaches like activist investing and macro trading.

Analytical

Valuation, Sentiment, Fundamentals, Technicals

Specific analytical methods and indicators.

How Agents Work

Each agent:

Analyzes selected stocks using their unique strategy
Generates trading signals (BUY, SELL, HOLD)
Provides detailed reasoning for decisions
Can use different LLM models
Works in parallel or sequential flows

📊 Backtesting

Backtesting lets you test strategies on historical data to see how they would have performed.

Setting Up a Backtest

Build your trading flow (same as regular analysis)
Click the "Backtest" button
Set date range:
- Start Date: e.g., 2024-01-01
- End Date: e.g., 2024-12-31
Set initial capital (e.g., $100,000)
Click "Run Backtest"

Backtest Results

The backtest shows:

Performance Metrics

Total return (percentage)
Sharpe ratio
Max drawdown
Win rate

Portfolio Details

Daily portfolio value
Final positions
Final cash
Trade history

Best Practices

Test on different time periods
Use realistic transaction costs
Consider market conditions
Compare multiple strategies
Review individual trade decisions

⌨️ Command Line Interface

For automation and scripting, use the CLI to run analyses from the command line.

Basic Usage

# Analyze stocks
poetry run python src/main.py --ticker AAPL,MSFT,NVDA

# Use specific agents
poetry run python src/main.py --ticker AAPL --analysts warren_buffett,peter_lynch

# Use Ollama (local models)
poetry run python src/main.py --ticker AAPL --ollama

# Set date range
poetry run python src/main.py --ticker AAPL --start-date 2024-01-01 --end-date 2024-03-01

Backtesting via CLI

# Run backtest
poetry run python src/backtester.py --ticker AAPL,MSFT,NVDA

# With date range
poetry run python src/backtester.py --ticker AAPL --start-date 2024-01-01 --end-date 2024-12-31

# Use Ollama
poetry run python src/backtester.py --ticker AAPL --ollama

CLI Options

--ticker - Comma-separated list of stock tickers (required)
--analysts - Comma-separated list of analyst IDs (optional)
--start-date - Start date for analysis (YYYY-MM-DD)
--end-date - End date for analysis (YYYY-MM-DD)
--ollama - Use Ollama for local LLM models
--model - Model name (default: gpt-4o)
--show-reasoning - Show agent reasoning in output

🎨 Theme Customization

AI Hedge Fund includes 11 beautiful themes to customize the interface appearance.

Available Themes

Light / Dark

Standard light and dark modes

Ocean

Blue and teal color scheme

Forest

Green natural theme

Sunset

Orange and pink gradient

Purple Dream

Purple and violet theme

Cyberpunk

Neon cyberpunk aesthetic

Midnight Blue

Deep blue dark theme

Emerald

Green and gold combination

Rose Gold

Elegant rose and gold

How to Change Theme

Go to Settings → Theme in the web interface
Click on desired theme
Theme applies immediately

🔧 Troubleshooting

Common Issues

"API Key Not Found"

Solution: Add API key in Settings → API Keys or `.env` file. Ensure key is correct and has credits.

"Backend Not Starting"

Check: Port 8000 is available

Solution: Kill existing process or change port:

pkill -f uvicorn

"Frontend Not Loading"

Check: Port 5173 is available

Solution: Kill existing process:

pkill -f vite

"Database Errors"

Solution: Delete `hedge_fund.db` and restart. Database is in project root.

"Poetry Not Found"

Solution: Install Poetry:

curl -sSL https://install.python-poetry.org | python3 -
export PATH="$HOME/.local/bin:$PATH"