# vivek1bharadwaj/trading-agents architecture

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

- Interactive diagram: https://gitdiagram.com/vivek1bharadwaj/trading-agents
- Repository: https://github.com/vivek1bharadwaj/trading-agents

## Overview

TradingAgents is a multi-agent financial research and trading framework, exposed through a CLI and reusable graph. The main workflow configures a dated instrument run, gathers market and contextual data, coordinates analyst reports and bullish/bearish research, then produces a trader proposal and portfolio decision; reports, memory, settlement and grid backtests support evaluation over time. The README documents social/news/macro analysis, risk debate and simulated execution. Some subsystem links are documented rather than confirmed in sampled implementation excerpts, so those are shown dashed with null evidence.

Main entry points: [`tradingagents/graph/trading_graph.py`](https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/graph/trading_graph.py) (Trading Graph), [`cli/main.py`](https://github.com/vivek1bharadwaj/trading-agents/blob/main/cli/main.py) (CLI), [`tradingagents/dataflows/vendors`](https://github.com/vivek1bharadwaj/trading-agents/tree/main/tradingagents/dataflows/vendors) (Market and News Vendors), [`tradingagents/agents/analysts`](https://github.com/vivek1bharadwaj/trading-agents/tree/main/tradingagents/agents/analysts) (Analyst Team)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Run Entry"]
  node_cli["CLI<br/>[main.py]"]
  node_run["Run Orchestration<br/>[run.py]"]
  node_backtest_cli["Backtest CLI<br/>[main.py]"]
  node_portfolio["Portfolio Input<br/>[portfolio.py]"]
end

subgraph group_data["Data Access"]
  node_data_router["Vendor Router<br/>[router.py]"]
  node_point_time["Point-in-Time Rules<br/>[date_window.py]"]
  node_symbols["Symbol Normalization<br/>[symbols.py]"]
  node_vendor_sources["Market and News Vendors"]
end

subgraph group_agents["Research and Decisions"]
  node_analysts["Analyst Team"]
  node_context["Prompt Context<br/>[context.py]"]
  node_researchers["Bull Bear Debate"]
  node_research_manager["Research Manager"]
  node_risk["Risk Debate"]
  node_trader["Trader<br/>[trader.py]"]
  node_portfolio_manager["Portfolio Manager"]
  node_post_screen["Social Screening<br/>[post_screen.py]"]
end

subgraph group_runtime["Run Services"]
  node_graph["Trading Graph<br/>[trading_graph.py]"]
  node_graph_setup["Workflow Setup<br/>[setup.py]"]
  node_analyst_dispatch["Analyst Dispatch"]
  node_llm["LLM Provider Clients"]
  node_memory["Decision Memory<br/>[log.py]"]
  node_reporting["Reports<br/>[reporting.py]"]
  node_checkpoint[("Run Checkpoints<br/>[checkpointer.py]")]
end

subgraph group_evaluation["Evaluation"]
  node_backtest["Grid Backtest<br/>[backtest.py]"]
  node_settlement["Outcome Settlement<br/>[settlement.py]"]
end

node_user(("Analyst User"))
node_exchange["Simulated Exchange"]
node_llm_service["LLM Services"]

node_user -->|"configures run"| node_cli
node_cli -->|"starts analysis"| node_run
node_cli -->|"requests backtest"| node_backtest_cli
node_cli -->|"loads holdings"| node_portfolio
node_run -->|"runs graph"| node_graph
node_backtest_cli -->|"runs grid"| node_backtest
node_backtest -->|"runs dated cases"| node_graph
node_graph -->|"builds workflow"| node_graph_setup
node_graph_setup -->|"registers analysts"| node_analyst_dispatch
node_analyst_dispatch -.->|"dispatches analysts"| node_analysts
node_analysts -.->|"uses prompt context"| node_context
node_analysts -.->|"requests research data"| node_data_router
node_data_router -->|"routes vendor calls"| node_vendor_sources
node_vendor_sources -.->|"applies date rules"| node_point_time
node_vendor_sources -.->|"normalizes tickers"| node_symbols
node_research_manager -.->|"coordinates debate"| node_researchers
node_researchers -.->|"informs risk debate"| node_risk
node_risk -.->|"informs trade plan"| node_trader
node_trader -.->|"submits proposal"| node_portfolio_manager
node_portfolio_manager -.->|"sends approved order"| node_exchange
node_graph -->|"creates clients"| node_llm
node_llm -.->|"requests completions"| node_llm_service
node_graph -->|"records decisions"| node_memory
node_graph -->|"writes report"| node_reporting
node_graph -->|"resumes runs"| node_checkpoint
node_graph -.->|"screens social posts"| node_post_screen
node_backtest -->|"reads run outcomes"| node_memory
node_settlement -.->|"settles decisions"| node_memory
node_graph -.->|"tracks realized outcomes"| node_settlement

click node_cli "https://github.com/vivek1bharadwaj/trading-agents/blob/main/cli/main.py"
click node_run "https://github.com/vivek1bharadwaj/trading-agents/blob/main/cli/run.py"
click node_backtest_cli "https://github.com/vivek1bharadwaj/trading-agents/blob/main/cli/main.py"
click node_graph "https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/graph/trading_graph.py"
click node_graph_setup "https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/graph/setup.py"
click node_analyst_dispatch "https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/graph/analyst_execution.py"
click node_analysts "https://github.com/vivek1bharadwaj/trading-agents/tree/main/tradingagents/agents/analysts"
click node_context "https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/agents/context.py"
click node_researchers "https://github.com/vivek1bharadwaj/trading-agents/tree/main/tradingagents/agents/researchers"
click node_research_manager "https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/agents/managers/research_manager.py"
click node_risk "https://github.com/vivek1bharadwaj/trading-agents/tree/main/tradingagents/agents/risk_mgmt"
click node_trader "https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/agents/trader/trader.py"
click node_portfolio_manager "https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/agents/managers/portfolio_manager.py"
click node_post_screen "https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/agents/post_screen.py"
click node_data_router "https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/dataflows/router.py"
click node_point_time "https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/dataflows/date_window.py"
click node_symbols "https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/dataflows/symbols.py"
click node_vendor_sources "https://github.com/vivek1bharadwaj/trading-agents/tree/main/tradingagents/dataflows/vendors"
click node_llm "https://github.com/vivek1bharadwaj/trading-agents/tree/main/tradingagents/llm_clients"
click node_memory "https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/memory/log.py"
click node_reporting "https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/reporting.py"
click node_checkpoint "https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/graph/checkpointer.py"
click node_portfolio "https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/portfolio.py"
click node_backtest "https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/backtest.py"
click node_settlement "https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/memory/settlement.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_run,node_backtest_cli,node_portfolio,node_user toneBlue
class node_data_router,node_point_time,node_symbols,node_vendor_sources toneAmber
class node_analysts,node_context,node_researchers,node_research_manager,node_risk,node_trader,node_portfolio_manager,node_post_screen toneMint
class node_graph,node_graph_setup,node_analyst_dispatch,node_llm,node_memory,node_reporting,node_checkpoint toneRose
class node_backtest,node_settlement,node_exchange,node_llm_service toneIndigo
```

## Components

### Run Entry

- [CLI](https://github.com/vivek1bharadwaj/trading-agents/blob/main/cli/main.py): `cli/main.py`
- [Run Orchestration](https://github.com/vivek1bharadwaj/trading-agents/blob/main/cli/run.py): `cli/run.py`
- [Backtest CLI](https://github.com/vivek1bharadwaj/trading-agents/blob/main/cli/main.py): `cli/main.py`
- [Portfolio Input](https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/portfolio.py): `tradingagents/portfolio.py`

### Data Access

- [Vendor Router](https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/dataflows/router.py): `tradingagents/dataflows/router.py`
- [Point-in-Time Rules](https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/dataflows/date_window.py): `tradingagents/dataflows/date_window.py`
- [Symbol Normalization](https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/dataflows/symbols.py): `tradingagents/dataflows/symbols.py`
- [Market and News Vendors](https://github.com/vivek1bharadwaj/trading-agents/tree/main/tradingagents/dataflows/vendors): `tradingagents/dataflows/vendors`

### Research and Decisions

- [Analyst Team](https://github.com/vivek1bharadwaj/trading-agents/tree/main/tradingagents/agents/analysts): `tradingagents/agents/analysts`
- [Prompt Context](https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/agents/context.py): `tradingagents/agents/context.py`
- [Bull Bear Debate](https://github.com/vivek1bharadwaj/trading-agents/tree/main/tradingagents/agents/researchers): `tradingagents/agents/researchers`
- [Research Manager](https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/agents/managers/research_manager.py): `tradingagents/agents/managers/research_manager.py`
- [Risk Debate](https://github.com/vivek1bharadwaj/trading-agents/tree/main/tradingagents/agents/risk_mgmt): `tradingagents/agents/risk_mgmt`
- [Trader](https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/agents/trader/trader.py): `tradingagents/agents/trader/trader.py`
- [Portfolio Manager](https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/agents/managers/portfolio_manager.py): `tradingagents/agents/managers/portfolio_manager.py`
- [Social Screening](https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/agents/post_screen.py): `tradingagents/agents/post_screen.py`

### Run Services

- [Trading Graph](https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/graph/trading_graph.py): `tradingagents/graph/trading_graph.py`
- [Workflow Setup](https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/graph/setup.py): `tradingagents/graph/setup.py`
- [Analyst Dispatch](https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/graph/analyst_execution.py): `tradingagents/graph/analyst_execution.py`
- [LLM Provider Clients](https://github.com/vivek1bharadwaj/trading-agents/tree/main/tradingagents/llm_clients): `tradingagents/llm_clients`
- [Decision Memory](https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/memory/log.py): `tradingagents/memory/log.py`
- [Reports](https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/reporting.py): `tradingagents/reporting.py`
- [Run Checkpoints](https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/graph/checkpointer.py): `tradingagents/graph/checkpointer.py`

### Evaluation

- [Grid Backtest](https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/backtest.py): `tradingagents/backtest.py`
- [Outcome Settlement](https://github.com/vivek1bharadwaj/trading-agents/blob/main/tradingagents/memory/settlement.py): `tradingagents/memory/settlement.py`

### Other components

- **Analyst User**
- **Simulated Exchange**
- **LLM Services**

## Connections

- Analyst User → CLI: configures run (evidence: `README.md`)
- CLI → Run Orchestration: starts analysis (evidence: `cli/main.py`)
- CLI → Backtest CLI: requests backtest (evidence: `cli/main.py`)
- CLI → Portfolio Input: loads holdings (evidence: `cli/main.py`)
- Run Orchestration → Trading Graph: runs graph
- Backtest CLI → Grid Backtest: runs grid (evidence: `cli/main.py`)
- Grid Backtest → Trading Graph: runs dated cases (evidence: `tradingagents/backtest.py`)
- Trading Graph → Workflow Setup: builds workflow (evidence: `tradingagents/graph/trading_graph.py`)
- Workflow Setup → Analyst Dispatch: registers analysts (evidence: `tradingagents/graph/setup.py`)
- Analyst Dispatch → Analyst Team: dispatches analysts
- Analyst Team → Prompt Context: uses prompt context
- Analyst Team → Vendor Router: requests research data
- Vendor Router → Market and News Vendors: routes vendor calls (evidence: `tradingagents/dataflows/router.py`)
- Market and News Vendors → Point-in-Time Rules: applies date rules (evidence: `tradingagents/dataflows/vendors/reddit.py`)
- Market and News Vendors → Symbol Normalization: normalizes tickers (evidence: `tradingagents/dataflows/vendors/reddit.py`)
- Research Manager → Bull Bear Debate: coordinates debate
- Bull Bear Debate → Risk Debate: informs risk debate
- Risk Debate → Trader: informs trade plan
- Trader → Portfolio Manager: submits proposal
- Portfolio Manager → Simulated Exchange: sends approved order (evidence: `README.md`)
- Trading Graph → LLM Provider Clients: creates clients (evidence: `tradingagents/graph/trading_graph.py`)
- LLM Provider Clients → LLM Services: requests completions
- Trading Graph → Decision Memory: records decisions (evidence: `tradingagents/graph/trading_graph.py`)
- Trading Graph → Reports: writes report (evidence: `tradingagents/graph/trading_graph.py`)
- Trading Graph → Run Checkpoints: resumes runs (evidence: `tradingagents/graph/trading_graph.py`)
- Trading Graph → Social Screening: screens social posts
- Grid Backtest → Decision Memory: reads run outcomes (evidence: `tradingagents/backtest.py`)
- Outcome Settlement → Decision Memory: settles decisions
- Trading Graph → Outcome Settlement: tracks realized outcomes (evidence: `tradingagents/graph/trading_graph.py`)