# vignesh-codes/tradingagents architecture

> Architecture diagram of the GitHub repository vignesh-codes/tradingagents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vignesh-codes/tradingagents
- Repository: https://github.com/vignesh-codes/tradingagents

## Overview

#### Purpose and entry points
TradingAgents is a Python, LangGraph-based multi-agent framework that produces simulated trading decisions from market data and LLM reasoning. Primary interactive entry point is `cli/main.py`; package/programmatic use centers on `tradingagents/graph/trading_graph.py` and is demonstrated by `main.py`. Runtime defaults are defined in `tradingagents/default_config.py`.

#### Orchestration graph
`TradingAgentsGraph` constructs and propagates the workflow, carrying ticker, date, reports, debate artifacts, and final decision through LangGraph nodes. Graph setup, routing/conditional progression, and inter-agent propagation are separated in:
- `tradingagents/graph/trading_graph.py`
- `tradingagents/graph/setup.py`
- `tradingagents/graph/conditional_logic.py`
- `tradingagents/graph/propagation.py`

#### Market-data boundary
Agent-facing tools abstract financial-data retrieval and indicator computation. The dataflow layer supports Alpha Vantage and Yahoo Finance, isolating provider-specific API calls from agent reasoning:
- `tradingagents/dataflows/interface.py`
- `tradingagents/dataflows/alpha_vantage.py`
- `tradingagents/dataflows/y_finance.py`
- `tradingagents/agents/utils/core_stock_tools.py`
- `tradingagents/agents/utils/technical_indicators_tools.py`

Alpha Vantage requires its API key; Yahoo Finance is another market/news source. Inputs are ticker and analysis date, with tools supplying fundamentals, prices, technicals, and news/social context.

#### Analyst stage
Specialist LLM agents generate independent reports on fundamentals, market/technical signals, news, and social sentiment. They are grounded by data tools and return artifacts into shared graph state:
- `tradingagents/agents/analysts/fundamentals_analyst.py`
- `tradingagents/agents/analysts/market_analyst.py`
- `tradingagents/agents/analysts/news_analyst.py`
- `tradingagents/agents/analysts/social_media_analyst.py`

#### Research, trade, and risk decision stages
Bull and bear researchers debate the analyst evidence; the research manager synthesizes that work. The trader proposes a transaction, then risk debaters provide aggressive, conservative, and neutral views before the portfolio manager approves or rejects the outcome:
- `tradingagents/agents/researchers/bull_researcher.py`
- `tradingagents/agents/researchers/bear_researcher.py`
- `tradingagents/agents/managers/research_manager.py`
- `tradingagents/agents/trader/trader.py`
- `tradingagents/agents/risk_mgmt/`
- `tradingagents/agents/managers/portfolio_manager.py`

Structured schemas and serialization form the important boundary between free-form model output and reliable downstream graph decisions: `tradingagents/agents/schemas.py`, `tradingagents/agents/utils/structured.py`.

#### LLM provider boundary
A client factory and model catalog normalize calls across OpenAI, Google, Anthropic, xAI-compatible providers, DeepSeek, Qwen, GLM, OpenRouter, Ollama, and Azure. Provider credentials are environment-driven, including enterprise settings:
- `tradingagents/llm_clients/factory.py`
- `tradingagents/llm_clients/base_client.py`
- `tradingagents/llm_clients/model_catalog.py`
- `tradingagents/llm_clients/openai_client.py`
- `tradingagents/llm_clients/azure_client.py`

#### Persistence, recovery, and deployment
Completed decisions feed a persistent memory/reflection loop, allowing later same-ticker and cross-ticker context to influence the portfolio-manager prompt. Optional per-ticker SQLite checkpoints persist LangGraph state after nodes and support interrupted-run resume:
- `tradingagents/agents/utils/memory.py`
- `tradingagents/graph/reflection.py`
- `tradingagents/graph/checkpointer.py`

The system runs locally as Python or in Docker via `Dockerfile` and `docker-compose.yml`; Docker Compose also supports an Ollama profile for local models.

Main entry points: [`tradingagents/graph/trading_graph.py`](https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/graph/trading_graph.py) (TradingAgentsGraph), [`tradingagents/llm_clients/factory.py`](https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/llm_clients/factory.py) (LLM client factory), [`tradingagents/agents/analysts/fundamentals_analyst.py`](https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/agents/analysts/fundamentals_analyst.py) (Specialist analysts), [`tradingagents/agents/managers/portfolio_manager.py`](https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/agents/managers/portfolio_manager.py) (Portfolio manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["CLI<br/>Python entry point<br/>[main.py]"]
  node_api["Programmatic API<br/>Python example<br/>[main.py]"]
  node_defaults["Runtime defaults<br/>configuration<br/>[default_config.py]"]
end

subgraph group_workflow["LangGraph workflow"]
  node_trading_graph{{"TradingAgentsGraph<br/>workflow orchestrator<br/>[trading_graph.py]"}}
  node_graph_setup["Graph setup<br/>workflow builder<br/>[setup.py]"]
  node_routing["Conditional routing<br/>workflow control"]
  node_propagation["State propagation<br/>workflow state<br/>[propagation.py]"]
end

subgraph group_data["Market data"]
  node_data_interface["Data tools interface<br/>market-data abstraction<br/>[interface.py]"]
  node_alpha_vantage["Alpha Vantage<br/>market-data provider<br/>[alpha_vantage.py]"]
  node_yahoo_finance["Yahoo Finance<br/>market-data provider<br/>[y_finance.py]"]
  node_stock_tools["Stock and technical tools<br/>agent tools"]
end

subgraph group_agents["Decision agents"]
  node_analysts["Specialist analysts<br/>LLM agent stage"]
  node_research["Research debate<br/>LLM agent stage<br/>[bull_researcher.py]"]
  node_research_manager["Research manager<br/>synthesis agent"]
  node_trader["Trader<br/>proposal agent<br/>[trader.py]"]
  node_risk_debate["Risk debate<br/>risk agent stage"]
  node_portfolio_manager["Portfolio manager<br/>decision agent"]
end

subgraph group_platform["Model and state services"]
  node_structured_output["Structured output<br/>schema boundary<br/>[schemas.py]"]
  node_llm_factory["LLM client factory<br/>provider gateway<br/>[factory.py]"]
  node_memory[("Memory and reflection<br/>persistent context<br/>[memory.py]")]
  node_checkpointer[("SQLite checkpointer<br/>workflow recovery<br/>[checkpointer.py]")]
end

node_cli -->|"runs"| node_trading_graph
node_api -->|"invokes"| node_trading_graph
node_defaults -.->|"configures"| node_trading_graph
node_trading_graph -->|"builds"| node_graph_setup
node_graph_setup -->|"defines routes"| node_routing
node_routing -->|"advances state"| node_propagation
node_trading_graph -->|"dispatches"| node_analysts
node_propagation -->|"analyst evidence"| node_research
node_research -->|"debate"| node_research_manager
node_research_manager -->|"research synthesis"| node_trader
node_trader -->|"trade proposal"| node_risk_debate
node_risk_debate -->|"risk views"| node_portfolio_manager
node_data_interface -->|"provider adapter"| node_alpha_vantage
node_data_interface -->|"provider adapter"| node_yahoo_finance
node_stock_tools -->|"retrieves data"| node_data_interface
node_analysts -->|"uses"| node_stock_tools
node_analysts -->|"reports"| node_structured_output
node_structured_output -->|"validated artifacts"| node_propagation
node_llm_factory -.->|"model calls"| node_analysts
node_llm_factory -.->|"model calls"| node_research
node_llm_factory -.->|"model calls"| node_trader
node_llm_factory -.->|"model calls"| node_portfolio_manager
node_portfolio_manager -->|"completed decisions"| node_memory
node_memory -.->|"prior context"| node_portfolio_manager
node_trading_graph -.->|"checkpoint state"| node_checkpointer

click node_cli "https://github.com/vignesh-codes/tradingagents/blob/main/cli/main.py"
click node_api "https://github.com/vignesh-codes/tradingagents/blob/main/main.py"
click node_defaults "https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/default_config.py"
click node_trading_graph "https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/graph/trading_graph.py"
click node_graph_setup "https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/graph/setup.py"
click node_routing "https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/graph/conditional_logic.py"
click node_propagation "https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/graph/propagation.py"
click node_data_interface "https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/dataflows/interface.py"
click node_alpha_vantage "https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/dataflows/alpha_vantage.py"
click node_yahoo_finance "https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/dataflows/y_finance.py"
click node_stock_tools "https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/agents/utils/core_stock_tools.py"
click node_analysts "https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/agents/analysts/fundamentals_analyst.py"
click node_research "https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/agents/researchers/bull_researcher.py"
click node_research_manager "https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/agents/managers/research_manager.py"
click node_trader "https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/agents/trader/trader.py"
click node_portfolio_manager "https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/agents/managers/portfolio_manager.py"
click node_structured_output "https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/agents/schemas.py"
click node_llm_factory "https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/llm_clients/factory.py"
click node_memory "https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/agents/utils/memory.py"
click node_checkpointer "https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/graph/checkpointer.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_api,node_defaults toneBlue
class node_trading_graph,node_graph_setup,node_routing,node_propagation toneAmber
class node_data_interface,node_alpha_vantage,node_yahoo_finance,node_stock_tools toneMint
class node_analysts,node_research,node_research_manager,node_trader,node_risk_debate,node_portfolio_manager toneRose
class node_structured_output,node_llm_factory,node_memory,node_checkpointer toneIndigo
```

## Components

### Entry points

- [CLI](https://github.com/vignesh-codes/tradingagents/blob/main/cli/main.py): Python entry point · `cli/main.py`
- [Programmatic API](https://github.com/vignesh-codes/tradingagents/blob/main/main.py): Python example · `main.py`
- [Runtime defaults](https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/default_config.py): configuration · `tradingagents/default_config.py`

### LangGraph workflow

- [TradingAgentsGraph](https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/graph/trading_graph.py): workflow orchestrator · Carries ticker, reports, debates, and final decision in shared state. · `tradingagents/graph/trading_graph.py`
- [Graph setup](https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/graph/setup.py): workflow builder · `tradingagents/graph/setup.py`
- [Conditional routing](https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/graph/conditional_logic.py): workflow control · `tradingagents/graph/conditional_logic.py`
- [State propagation](https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/graph/propagation.py): workflow state · `tradingagents/graph/propagation.py`

### Market data

- [Data tools interface](https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/dataflows/interface.py): market-data abstraction · `tradingagents/dataflows/interface.py`
- [Alpha Vantage](https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/dataflows/alpha_vantage.py): market-data provider · API-key-backed market-data provider. · `tradingagents/dataflows/alpha_vantage.py`
- [Yahoo Finance](https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/dataflows/y_finance.py): market-data provider · `tradingagents/dataflows/y_finance.py`
- [Stock and technical tools](https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/agents/utils/core_stock_tools.py): agent tools · Supplies fundamentals, prices, technicals, and context. · `tradingagents/agents/utils/core_stock_tools.py`

### Decision agents

- [Specialist analysts](https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/agents/analysts/fundamentals_analyst.py): LLM agent stage · Fundamentals, market, news, and social reports. · `tradingagents/agents/analysts/fundamentals_analyst.py`
- [Research debate](https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/agents/researchers/bull_researcher.py): LLM agent stage · Bull and bear researchers assess analyst evidence. · `tradingagents/agents/researchers/bull_researcher.py`
- [Research manager](https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/agents/managers/research_manager.py): synthesis agent · `tradingagents/agents/managers/research_manager.py`
- [Trader](https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/agents/trader/trader.py): proposal agent · `tradingagents/agents/trader/trader.py`
- **Risk debate**: risk agent stage · Aggressive, conservative, and neutral risk views.
- [Portfolio manager](https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/agents/managers/portfolio_manager.py): decision agent · Approves or rejects the trade outcome. · `tradingagents/agents/managers/portfolio_manager.py`

### Model and state services

- [Structured output](https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/agents/schemas.py): schema boundary · Serializes model output into reliable graph decisions. · `tradingagents/agents/schemas.py`
- [LLM client factory](https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/llm_clients/factory.py): provider gateway · Normalizes provider and model selection. · `tradingagents/llm_clients/factory.py`
- [Memory and reflection](https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/agents/utils/memory.py): persistent context · Feeds prior ticker context into portfolio decisions. · `tradingagents/agents/utils/memory.py`
- [SQLite checkpointer](https://github.com/vignesh-codes/tradingagents/blob/main/tradingagents/graph/checkpointer.py): workflow recovery · Persists per-ticker state and enables resume. · `tradingagents/graph/checkpointer.py`

## Connections

- CLI → TradingAgentsGraph: runs
- Programmatic API → TradingAgentsGraph: invokes
- Runtime defaults → TradingAgentsGraph: configures
- TradingAgentsGraph → Graph setup: builds
- Graph setup → Conditional routing: defines routes
- Conditional routing → State propagation: advances state
- TradingAgentsGraph → Specialist analysts: dispatches
- State propagation → Research debate: analyst evidence
- Research debate → Research manager: debate
- Research manager → Trader: research synthesis
- Trader → Risk debate: trade proposal
- Risk debate → Portfolio manager: risk views
- Data tools interface → Alpha Vantage: provider adapter
- Data tools interface → Yahoo Finance: provider adapter
- Stock and technical tools → Data tools interface: retrieves data
- Specialist analysts → Stock and technical tools: uses
- Specialist analysts → Structured output: reports
- Structured output → State propagation: validated artifacts
- LLM client factory → Specialist analysts: model calls
- LLM client factory → Research debate: model calls
- LLM client factory → Trader: model calls
- LLM client factory → Portfolio manager: model calls
- Portfolio manager → Memory and reflection: completed decisions
- Memory and reflection → Portfolio manager: prior context
- TradingAgentsGraph → SQLite checkpointer: checkpoint state