# 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

```bash
# 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

```bash
# 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

```bash
# 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`).