charieswei
/
TradingAgents
mirror of https://github.com/TauricResearch/TradingAgents.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
TradingAgents/CLAUDE.md

6.7 KiB
Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

TradingAgents is a multi-agent LLM financial trading framework built with LangGraph. It simulates a trading firm with specialized agents: analysts (market, social, news, fundamentals), researchers (bull/bear), trader, and risk management teams. The system supports multiple LLM providers (OpenAI, Anthropic, Google, xAI, OpenRouter, Ollama) and data vendors (Yahoo Finance, Alpha Vantage).

Essential Commands

Python Environment

Always activate the project's virtual environment before running Python commands:

# Windows
.venv\Scripts\activate
# Linux/macOS
source .venv/bin/activate

Installation (requires Python >=3.10)

pip install -r requirements.txt
# OR for editable install with CLI entry point
pip install -e .

CLI Usage

python -m cli.main
# or if installed via pip install -e .
tradingagents

Python API Usage

from tradingagents.graph.trading_graph import TradingAgentsGraph
from tradingagents.default_config import DEFAULT_CONFIG

ta = TradingAgentsGraph(debug=True, config=DEFAULT_CONFIG.copy())
_, decision = ta.propagate("NVDA", "2026-01-15")
print(decision)

# After observing actual returns, memorize mistakes for future runs
# ta.reflect_and_remember(returns)  # parameter is the position returns (e.g. 1000)

Testing and Linting

No formal test suite or linting configuration exists. test.py at root is a manual smoke test for Yahoo Finance data functions.

Environment Variables

Set via .env file (loaded with python-dotenv) or shell exports. Only the provider you use is required:

OPENAI_API_KEY=...          # OpenAI (GPT)
GOOGLE_API_KEY=...          # Google (Gemini)
ANTHROPIC_API_KEY=...       # Anthropic (Claude)
XAI_API_KEY=...             # xAI (Grok)
OPENROUTER_API_KEY=...      # OpenRouter
ZHIPU_API_KEY=...           # Zhipu AI
ALPHA_VANTAGE_API_KEY=...   # Alpha Vantage (optional, for non-yfinance data)
TRADINGAGENTS_RESULTS_DIR=... # Optional results directory override

Architecture

Core Workflow (LangGraph State Machine)

The trading graph follows a sequential multi-phase workflow:

  1. Analyst Phase - Each selected analyst runs sequentially, uses tools to gather data, clears messages after completion
  2. Research Phase - Bull/Bear researchers debate with analyst reports as context; Research Manager finalizes after max_debate_rounds
  3. Trading Phase - Trader synthesizes research into investment plan
  4. Risk Phase - Aggressive/Conservative/Neutral agents debate; Risk Judge finalizes after max_risk_discuss_rounds

Key files:

  • tradingagents/graph/trading_graph.py - Main TradingAgentsGraph class
  • tradingagents/graph/setup.py - GraphSetup for building workflow
  • tradingagents/graph/conditional_logic.py - Routing logic
  • tradingagents/graph/propagation.py - State initialization

Directory Structure

cli/                    # Command-line interface (Typer-based)
tradingagents/
  agents/
    analysts/           # Initial analysis agents
    researchers/        # Bull/bear researchers + manager
    managers/           # Research and risk managers
    trader/            # Trading decision agent
    risk_mgmt/         # Risk assessment agents
    utils/             # Agent states, tools, memory (BM25)
  graph/               # LangGraph workflow orchestration
  dataflows/           # Data source abstraction (vendor routing)
  llm_clients/         # Multi-provider LLM factory

LLM Client Factory

tradingagents/llm_clients/factory.py implements the factory pattern for creating LLM clients. Base client class in base_client.py with provider-specific implementations (OpenAI, Anthropic, Google). Provider-specific thinking configuration:

  • Google: google_thinking_level ("high", "minimal")
  • OpenAI: openai_reasoning_effort ("medium", "high", "low")

Data Vendor Routing

tradingagents/dataflows/interface.py routes tool calls to vendor implementations. Configuration via default_config.py:

  • Category-level: data_vendors["core_stock_apis"] = "yfinance"
  • Tool-level override: tool_vendors["get_stock_data"] = "alpha_vantage"

Supported vendors: Yahoo Finance (free, default), Alpha Vantage (requires API key).

Agent State Management

Agent states are TypedDict classes in agents/utils/agent_states.py:

  • AgentState - Base state for analyst agents
  • InvestDebateState - Research team debate state
  • RiskDebateState - Risk management debate state

Each agent function takes state and returns state updates. Messages are cleared between phases to manage context window.

Tool Definition

All data tools use @tool decorator from langchain_core.tools and are defined in agents/utils/. Tools route via dataflows.interface.route_to_vendor() to vendor implementations.

Configuration

tradingagents/default_config.py defines the default configuration:

  • llm_provider - "openai", "google", "anthropic", "xai", "openrouter", "ollama"
  • deep_think_llm - Model for complex reasoning (default: "gpt-5.2")
  • quick_think_llm - Model for quick tasks (default: "gpt-5-mini")
  • backend_url - Custom API endpoint (default: OpenAI's endpoint)
  • max_debate_rounds - Research team debate iterations (default: 1)
  • max_risk_discuss_rounds - Risk team debate iterations (default: 1)
  • max_recur_limit - LangGraph recursion limit (default: 100)
  • data_vendors - Per-category vendor selection (categories: core_stock_apis, technical_indicators, fundamental_data, news_data)
  • tool_vendors - Per-tool vendor overrides (takes precedence over category-level)

Copy and modify DEFAULT_CONFIG to customize. Always use .copy() to avoid mutating the shared default.

Important Patterns

  1. Agent Functions - Each agent is a function agent(state) -> dict returning state updates
  2. Message Clearing - Analysts clear messages after completion to prevent context bloat
  3. Tool Decorators - Use @tool from langchain_core.tools for all data tools
  4. Factory Pattern - LLM clients via create_llm_client() in llm_clients/factory.py
  5. Memory - BM25-based lexical matching in agents/utils/memory.py (no API calls, offline-capable)
  6. Caching - Data cached in tradingagents/dataflows/data_cache/

Results and Output

Analysis logs and reports are saved to results/ directory (configurable via TRADINGAGENTS_RESULTS_DIR env var). The CLI provides real-time progress display using Rich library.

Key Entry Points

  • CLI: cli/main.py (Typer app)
  • Trading Graph: tradingagents/graph/trading_graph.py - TradingAgentsGraph.propagate()
  • LLM Factory: tradingagents/llm_clients/factory.py - create_llm_client()
  • Data Interface: tradingagents/dataflows/interface.py - route_to_vendor()