3.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 trading framework (by TauricResearch) that simulates a real trading firm using LangGraph. Agents are organized into teams: Analysts (4 types), Researchers (bull/bear debate), Trader, Risk Management (3-way debate), and Portfolio Manager.

Build & Install

# Install (Python >=3.10, 3.13 recommended)
pip install .
# or with uv:
uv pip install .

Environment variables go in .env (see .env.example for required API keys).

Running

# CLI (installed entry point)
tradingagents

# Programmatic usage (see main.py for example)
from tradingagents.graph.trading_graph import TradingAgentsGraph
ta = TradingAgentsGraph(debug=True, config=config)
_, decision = ta.propagate("NVDA", "2024-05-10")

Testing

# Run all tests (unittest-based, no pytest)
python -m unittest discover -s tests

# Run a single test module
python -m unittest tests.test_model_validation
python -m unittest tests.test_ticker_symbol_handling
python -m unittest tests.test_google_api_key

No linter or formatter is formally configured (Ruff may be used informally).

Architecture

LangGraph State Machine

The core is a StateGraph compiled in tradingagents/graph/setup.py:

START -> Market Analyst -> Social Media Analyst -> News Analyst -> Fundamentals Analyst
      -> Bull/Bear Researcher Debate (multi-round)
      -> Research Manager (deep_think_llm)
      -> Trader
      -> Risk Debate: Aggressive/Conservative/Neutral (multi-round)
      -> Portfolio Manager (deep_think_llm) -> END

State flows through AgentState (extends LangGraph MessagesState) defined in tradingagents/agents/utils/agent_states.py. Nested InvestDebateState and RiskDebateState track debate rounds.

Two-LLM Tier System

quick_think_llm: Analysts, researchers, risk debators, trader
deep_think_llm: Research Manager and Portfolio Manager (final decision-makers)

Key Module Relationships

tradingagents/graph/trading_graph.py — TradingAgentsGraph is the main orchestrator. Creates LLM clients, initializes agent nodes, compiles the graph, and exposes propagate(ticker, date).
tradingagents/graph/setup.py — GraphSetup wires agent nodes into the StateGraph with conditional edges from conditional_logic.py.
tradingagents/agents/ — Each agent type has a create_*() factory function returning a callable graph node. All re-exported from __init__.py.
tradingagents/dataflows/interface.py — Vendor routing (strategy pattern) dispatches data calls to yfinance (default) or alpha_vantage, with automatic fallback on rate limits.
tradingagents/llm_clients/factory.py — create_llm_client() dispatches to provider-specific clients (OpenAIClient handles openai/ollama/openrouter/xai, plus AnthropicClient, GoogleClient). All extend BaseLLMClient ABC.
tradingagents/agents/utils/memory.py — FinancialSituationMemory uses BM25 retrieval for learning from past decisions via reflect_and_remember().

Configuration

tradingagents/default_config.py holds DEFAULT_CONFIG with: LLM provider/model settings, debate round limits, data vendor routing, results directory (overridable via TRADINGAGENTS_RESULTS_DIR env var), and provider-specific thinking configs.

CLI

cli/main.py is a Typer app (~50K) providing an interactive Rich UI. Entry point registered as tradingagents console script.

Docker

Multi-stage Dockerfile (python:3.12-slim). docker-compose.yml has optional Ollama profile (docker compose --profile ollama up).

3.7 KiB Raw Blame History