How virattt/ai-hedge-fund works
AI Hedge Fund is an educational research and trading-simulation application. A user builds or loads a ticker-free fund mandate, supplies a universe, then runs a cycle: point-in-time market data feeds alpha models, signals are blended, risk limits are applied, orders are simulated, and a cycle record/NAV is returned. The same fund can be iterated for backtests; independent event studies compute earnings CARs. The tree and excerpts support these major paths, but some TUI and backtest details were unsampled.
Main entry points: run_cycle.py Cycle Orchestrator · client.py Data Client · run.py CLI Runner · llm_agent.py LLM Investor Agents
Components 22
User Interfaces
- CLI Runner
hedge_fund/run.py - Interactive TUI
hedge_fund/tui/app.py
Fund Runtime
- Fund Mandate
hedge_fund/fund/spec.py - Cycle Orchestrator
hedge_fund/pipeline/run_cycle.py - Portfolio Construction
hedge_fund/portfolio/construction.py - Risk Limits
hedge_fund/risk/limits.py - Order Builder
hedge_fund/pipeline/execution.py - Simulated Broker
hedge_fund/brokers/sim.py - Cycle Records
hedge_fund/pipeline/models.py
Research Stack
- Data Client
hedge_fund/data/client.py - Cached Data
hedge_fund/data/cached.py - Fundamentals Snapshot
hedge_fund/features/snapshot.py - Alpha Models
hedge_fund/signals/base.py - LLM Investor Agents
hedge_fund/signals/llm_agent.py - Prompt Cache
hedge_fund/llm/cache.py - LLM Client
hedge_fund/llm/client.py
Analysis
- Backtest Engine
hedge_fund/backtesting/engine.py - Fund Backtest
hedge_fund/backtesting/fund.py - Event Study
hedge_fund/event_study/engine.py
Other components
- Investor User
- Financial Data API
- LLM Providers
Connections 29
- Investor User → CLI Runner: runs mandate
- Investor User → Interactive TUI: builds fund
- CLI Runner → Fund Mandate: loads spec
- Interactive TUI → Fund Mandate: writes mandate
- CLI Runner → Cycle Orchestrator: runs cycle
- CLI Runner → Fund Backtest: starts backtest
- Interactive TUI → Fund Backtest: starts backtest
- Fund Mandate → Cycle Orchestrator: configures fund
- Cycle Orchestrator → Cached Data: fetches marks
- Cached Data → Data Client: delegates misses
- Data Client → Financial Data API: requests data
- Cycle Orchestrator → Alpha Models: requests signals
- Alpha Models → LLM Investor Agents: dispatches agents
- LLM Investor Agents → Fundamentals Snapshot: builds context
- Fundamentals Snapshot → Data Client: reads fundamentals
- LLM Investor Agents → Prompt Cache: reads writes prompts
- LLM Investor Agents → LLM Client: requests completion
- LLM Client → LLM Providers: calls model
- Cycle Orchestrator → Portfolio Construction: blends signals
- Cycle Orchestrator → Risk Limits: applies limits
- Cycle Orchestrator → Order Builder: builds orders
- Cycle Orchestrator → Simulated Broker: submits orders
- Cycle Orchestrator → Cycle Records: returns record
- Fund Backtest → Cycle Orchestrator: repeats cycles
- Fund Backtest → Data Client: loads history
- Backtest Engine → Alpha Models: queries model
- Backtest Engine → Data Client: loads prices
- Event Study → Data Client: loads earnings prices
- Event Study → Financial Data API: retrieves benchmark