# virattt/ai-hedge-fund architecture

> Architecture diagram of the GitHub repository virattt/ai-hedge-fund, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/virattt/ai-hedge-fund
- Repository: https://github.com/virattt/ai-hedge-fund
- Video tour (about a minute): https://gitdiagram.com/virattt/ai-hedge-fund/video

## Overview

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: [`hedge_fund/pipeline/run_cycle.py`](https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/pipeline/run_cycle.py) (Cycle Orchestrator), [`hedge_fund/data/client.py`](https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/data/client.py) (Data Client), [`hedge_fund/run.py`](https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/run.py) (CLI Runner), [`hedge_fund/signals/llm_agent.py`](https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/signals/llm_agent.py) (LLM Investor Agents)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_cli["CLI Runner<br/>[run.py]"]
  node_tui["Interactive TUI<br/>[app.py]"]
end

subgraph group_fund_runtime["Fund Runtime"]
  node_mandate["Fund Mandate<br/>[spec.py]"]
  node_cycle["Cycle Orchestrator<br/>[run_cycle.py]"]
  node_portfolio["Portfolio Construction<br/>[construction.py]"]
  node_risk["Risk Limits<br/>[limits.py]"]
  node_orders["Order Builder<br/>[execution.py]"]
  node_broker["Simulated Broker<br/>[sim.py]"]
  node_records["Cycle Records<br/>[models.py]"]
end

subgraph group_research["Research Stack"]
  node_data_client["Data Client<br/>[client.py]"]
  node_data_cache["Cached Data<br/>[cached.py]"]
  node_snapshot["Fundamentals Snapshot<br/>[snapshot.py]"]
  node_alpha_models["Alpha Models<br/>[base.py]"]
  node_llm_agent["LLM Investor Agents<br/>[llm_agent.py]"]
  node_llm_cache[("Prompt Cache<br/>[cache.py]")]
  node_llm_client["LLM Client<br/>[client.py]"]
end

subgraph group_analysis["Analysis"]
  node_backtest["Backtest Engine<br/>[engine.py]"]
  node_fund_backtest["Fund Backtest<br/>[fund.py]"]
  node_event_study["Event Study<br/>[engine.py]"]
end

node_user(("Investor User"))
node_market_api["Financial Data API"]
node_llm_provider["LLM Providers"]

node_user -->|"runs mandate"| node_cli
node_user -->|"builds fund"| node_tui
node_cli -->|"loads spec"| node_mandate
node_tui -->|"writes mandate"| node_mandate
node_cli -->|"runs cycle"| node_cycle
node_cli -->|"starts backtest"| node_fund_backtest
node_tui -->|"starts backtest"| node_fund_backtest
node_mandate -->|"configures fund"| node_cycle
node_cycle -->|"fetches marks"| node_data_cache
node_data_cache -->|"delegates misses"| node_data_client
node_data_client -->|"requests data"| node_market_api
node_cycle -->|"requests signals"| node_alpha_models
node_alpha_models -.->|"dispatches agents"| node_llm_agent
node_llm_agent -->|"builds context"| node_snapshot
node_snapshot -->|"reads fundamentals"| node_data_client
node_llm_agent -->|"reads writes prompts"| node_llm_cache
node_llm_agent -->|"requests completion"| node_llm_client
node_llm_client -->|"calls model"| node_llm_provider
node_cycle -->|"blends signals"| node_portfolio
node_cycle -->|"applies limits"| node_risk
node_cycle -->|"builds orders"| node_orders
node_cycle -->|"submits orders"| node_broker
node_cycle -->|"returns record"| node_records
node_fund_backtest -->|"repeats cycles"| node_cycle
node_fund_backtest -->|"loads history"| node_data_client
node_backtest -->|"queries model"| node_alpha_models
node_backtest -->|"loads prices"| node_data_client
node_event_study -->|"loads earnings prices"| node_data_client
node_event_study -->|"retrieves benchmark"| node_market_api

click node_cli "https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/run.py"
click node_tui "https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/tui/app.py"
click node_mandate "https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/fund/spec.py"
click node_cycle "https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/pipeline/run_cycle.py"
click node_portfolio "https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/portfolio/construction.py"
click node_risk "https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/risk/limits.py"
click node_orders "https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/pipeline/execution.py"
click node_broker "https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/brokers/sim.py"
click node_records "https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/pipeline/models.py"
click node_data_client "https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/data/client.py"
click node_data_cache "https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/data/cached.py"
click node_snapshot "https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/features/snapshot.py"
click node_alpha_models "https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/signals/base.py"
click node_llm_agent "https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/signals/llm_agent.py"
click node_llm_cache "https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/llm/cache.py"
click node_llm_client "https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/llm/client.py"
click node_backtest "https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/backtesting/engine.py"
click node_fund_backtest "https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/backtesting/fund.py"
click node_event_study "https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/event_study/engine.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_tui,node_user toneBlue
class node_mandate,node_cycle,node_portfolio,node_risk,node_orders,node_broker,node_records toneAmber
class node_data_client,node_data_cache,node_snapshot,node_alpha_models,node_llm_agent,node_llm_cache,node_llm_client,node_market_api toneMint
class node_backtest,node_fund_backtest,node_event_study toneRose
class node_llm_provider toneIndigo
```

## Components

### User Interfaces

- [CLI Runner](https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/run.py): `hedge_fund/run.py`
- [Interactive TUI](https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/tui/app.py): `hedge_fund/tui/app.py`

### Fund Runtime

- [Fund Mandate](https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/fund/spec.py): `hedge_fund/fund/spec.py`
- [Cycle Orchestrator](https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/pipeline/run_cycle.py): `hedge_fund/pipeline/run_cycle.py`
- [Portfolio Construction](https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/portfolio/construction.py): `hedge_fund/portfolio/construction.py`
- [Risk Limits](https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/risk/limits.py): `hedge_fund/risk/limits.py`
- [Order Builder](https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/pipeline/execution.py): `hedge_fund/pipeline/execution.py`
- [Simulated Broker](https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/brokers/sim.py): `hedge_fund/brokers/sim.py`
- [Cycle Records](https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/pipeline/models.py): `hedge_fund/pipeline/models.py`

### Research Stack

- [Data Client](https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/data/client.py): `hedge_fund/data/client.py`
- [Cached Data](https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/data/cached.py): `hedge_fund/data/cached.py`
- [Fundamentals Snapshot](https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/features/snapshot.py): `hedge_fund/features/snapshot.py`
- [Alpha Models](https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/signals/base.py): `hedge_fund/signals/base.py`
- [LLM Investor Agents](https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/signals/llm_agent.py): `hedge_fund/signals/llm_agent.py`
- [Prompt Cache](https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/llm/cache.py): `hedge_fund/llm/cache.py`
- [LLM Client](https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/llm/client.py): `hedge_fund/llm/client.py`

### Analysis

- [Backtest Engine](https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/backtesting/engine.py): `hedge_fund/backtesting/engine.py`
- [Fund Backtest](https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/backtesting/fund.py): `hedge_fund/backtesting/fund.py`
- [Event Study](https://github.com/virattt/ai-hedge-fund/blob/main/hedge_fund/event_study/engine.py): `hedge_fund/event_study/engine.py`

### Other components

- **Investor User**
- **Financial Data API**
- **LLM Providers**

## Connections

- 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
