152 lines
6.7 KiB
Markdown
152 lines
6.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 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:
|
|
```bash
|
|
# Windows
|
|
.venv\Scripts\activate
|
|
# Linux/macOS
|
|
source .venv/bin/activate
|
|
```
|
|
|
|
### Installation (requires Python >=3.10)
|
|
```bash
|
|
pip install -r requirements.txt
|
|
# OR for editable install with CLI entry point
|
|
pip install -e .
|
|
```
|
|
|
|
### CLI Usage
|
|
```bash
|
|
python -m cli.main
|
|
# or if installed via pip install -e .
|
|
tradingagents
|
|
```
|
|
|
|
### Python API Usage
|
|
```python
|
|
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:
|
|
```bash
|
|
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()`
|