88 lines
3.7 KiB
Markdown
88 lines
3.7 KiB
Markdown
# 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`).
|