diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..915a6bc4 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,273 @@ +# 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 that mirrors real-world trading firm dynamics. The framework uses specialized LLM agents (analysts, researchers, traders, and risk managers) to collaboratively evaluate market conditions and make informed trading decisions. + +**Research Paper**: arXiv:2412.20138 + +## Core Architecture + +### Multi-Agent Pipeline Flow + +The system follows a sequential pipeline mimicking institutional trading: + +``` +Analyst Team → Research Team → Trader → Risk Management → Portfolio Manager +``` + +### Agent Teams Structure + +**1. Analyst Team** (`tradingagents/agents/analysts/`) +- `market_analyst.py` - Technical analysis using MACD, RSI, price patterns +- `social_media_analyst.py` - Sentiment analysis from social media +- `news_analyst.py` - Global news and macroeconomic indicators +- `fundamentals_analyst.py` - Company financials and intrinsic values + +**2. Research Team** (`tradingagents/agents/researchers/`) +- `bull_researcher.py` - Bullish perspective analysis +- `bear_researcher.py` - Bearish perspective analysis +- `research_manager.py` - Debate moderator and final decision maker + +**3. Trading Team** (`tradingagents/agents/trader/`) +- `trader.py` - Composes reports and makes trading decisions + +**4. Risk Management** (`tradingagents/agents/risk_mgmt/`) +- `aggresive_debator.py` - High-risk tolerance perspective +- `conservative_debator.py` - Low-risk tolerance perspective +- `neutral_debator.py` - Balanced risk perspective + +**5. Portfolio Management** (`tradingagents/agents/managers/`) +- `risk_manager.py` - Final approval/rejection of trades + +### State Management + +States are defined in `tradingagents/agents/utils/agent_states.py`: + +- **AgentState**: Main state flowing through the graph (company, date, reports, decisions) +- **InvestDebateState**: Research team debate state (bull/bear history, judge decision) +- **RiskDebateState**: Risk management debate state (risky/safe/neutral perspectives) + +### Graph Orchestration + +The LangGraph workflow is managed in `tradingagents/graph/`: + +- `trading_graph.py` - Main orchestration class (`TradingAgentsGraph`) +- `setup.py` - Graph construction and node configuration (`GraphSetup`) +- `propagation.py` - State initialization and execution (`Propagator`) +- `conditional_logic.py` - Routing logic between nodes (`ConditionalLogic`) +- `reflection.py` - Learning from past decisions (`Reflector`) +- `signal_processing.py` - Extract trading signals from decisions (`SignalProcessor`) + +### Data Layer + +Data flows through an abstraction layer in `tradingagents/dataflows/`: + +**Configuration System**: +- `config.py` - Global config management with `set_config()` and `get_config()` +- `interface.py` - Abstract tool interface that routes to appropriate vendor +- `default_config.py` - Default settings including data vendors + +**Vendor Implementations**: +- `alpha_vantage*.py` - Alpha Vantage API (fundamental, news, stock data) +- `y_finance.py` / `yfin_utils.py` - Yahoo Finance API (market data, indicators) +- `google.py` / `googlenews_utils.py` - Google News (alternative news source) +- `local.py` - Local data vendor for offline testing +- `openai.py` - LLM-based data vendor for fundamental/news analysis + +**Tool Abstraction** (`tradingagents/agents/utils/agent_utils.py`): +Abstract functions automatically route to configured vendor: +- `get_stock_data()`, `get_indicators()` - Market data +- `get_fundamentals()`, `get_balance_sheet()`, `get_cashflow()`, `get_income_statement()` - Fundamental data +- `get_news()`, `get_global_news()` - News data +- `get_insider_sentiment()`, `get_insider_transactions()` - Insider data + +## Installation and Setup + +### Environment Setup + +```bash +# Clone and create virtual environment +conda create -n tradingagents python=3.13 +conda activate tradingagents + +# Install dependencies +pip install -r requirements.txt +``` + +### API Keys Configuration + +**Required APIs**: +- OpenAI API (for LLM agents) +- Alpha Vantage API (for fundamental and news data - default config) + +**Setup via environment variables**: +```bash +export OPENAI_API_KEY=$YOUR_OPENAI_API_KEY +export ALPHA_VANTAGE_API_KEY=$YOUR_ALPHA_VANTAGE_API_KEY +``` + +**Setup via .env file**: +```bash +cp .env.example .env +# Edit .env with your actual API keys +``` + +### Data Vendor Configuration + +Modify `tradingagents/default_config.py` to change data sources: + +```python +"data_vendors": { + "core_stock_apis": "yfinance", # yfinance, alpha_vantage, local + "technical_indicators": "yfinance", # yfinance, alpha_vantage, local + "fundamental_data": "alpha_vantage", # openai, alpha_vantage, local + "news_data": "alpha_vantage", # openai, alpha_vantage, google, local +} +``` + +## Running the Framework + +### CLI Mode (Interactive) + +```bash +python -m cli.main +``` + +This launches an interactive CLI with: +- Ticker selection +- Date selection +- Analyst team selection +- Research depth configuration (debate rounds) +- LLM provider and model selection +- Real-time progress tracking + +### Python API Mode + +**Basic usage** (`main.py`): +```python +from tradingagents.graph.trading_graph import TradingAgentsGraph +from tradingagents.default_config import DEFAULT_CONFIG + +ta = TradingAgentsGraph(debug=True, config=DEFAULT_CONFIG.copy()) + +# Run analysis +_, decision = ta.propagate("NVDA", "2024-05-10") +print(decision) +``` + +**Custom configuration**: +```python +config = DEFAULT_CONFIG.copy() +config["deep_think_llm"] = "gpt-4o-mini" # Deep thinking model +config["quick_think_llm"] = "gpt-4o-mini" # Quick thinking model +config["max_debate_rounds"] = 1 # Research debate rounds +config["max_risk_discuss_rounds"] = 1 # Risk debate rounds + +# LLM provider options: "openai", "anthropic", "google", "ollama", "openrouter" +config["llm_provider"] = "openai" +config["backend_url"] = "https://api.openai.com/v1" + +ta = TradingAgentsGraph(debug=True, config=config) +_, decision = ta.propagate("AAPL", "2024-05-10") +``` + +**Reflection and learning**: +```python +# After getting returns, reflect and update memory +ta.reflect_and_remember(returns_losses=1000) # Positive returns +``` + +## LLM Provider Support + +The framework supports multiple LLM providers (configured in `tradingagents/graph/trading_graph.py:75-85`): + +- **OpenAI**: `llm_provider: "openai"`, backend_url: `https://api.openai.com/v1` +- **Anthropic**: `llm_provider: "anthropic"` +- **Google**: `llm_provider: "google"` +- **Ollama**: `llm_provider: "ollama"` (local models) +- **OpenRouter**: `llm_provider: "openrouter"` + +## Key Configuration Parameters + +Located in `tradingagents/default_config.py`: + +- `results_dir` - Output directory for results (default: `./results`) +- `deep_think_llm` - Model for complex reasoning (default: `o4-mini`) +- `quick_think_llm` - Model for quick tasks (default: `gpt-4o-mini`) +- `max_debate_rounds` - Research team debate rounds (default: `1`) +- `max_risk_discuss_rounds` - Risk team debate rounds (default: `1`) +- `data_vendors` - Data source configuration per category + +## Output Structure + +Results are saved to: +``` +results/ +└── {TICKER}/ + └── {DATE}/ + ├── reports/ + │ ├── market_report.md + │ ├── sentiment_report.md + │ ├── news_report.md + │ ├── fundamentals_report.md + │ ├── investment_plan.md + │ ├── trader_investment_plan.md + │ └── final_trade_decision.md + └── message_tool.log + +eval_results/ +└── {TICKER}/ + └── TradingAgentsStrategy_logs/ + └── full_states_log_{DATE}.json +``` + +## Memory System + +The framework includes a reflection-based learning system (`tradingagents/agents/utils/memory.py`): + +- **FinancialSituationMemory**: Stores past decisions and outcomes +- Memories are agent-specific (bull, bear, trader, judge, risk manager) +- Uses ChromaDB for vector storage +- Enables learning from past trading mistakes + +Memory is updated via: +```python +ta.reflect_and_remember(returns_losses) +``` + +## Testing and Development + +**Cost-saving for testing**: +- Use `gpt-4o-mini` or `gpt-4.1-mini` instead of `o1-preview`/`gpt-4o` +- Set `max_debate_rounds: 1` to reduce API calls +- Use `local` data vendor with pre-downloaded data + +**Debug mode**: +```python +ta = TradingAgentsGraph(debug=True, config=config) +``` +This enables: +- LangGraph state tracing +- Pretty-printed message outputs +- Detailed logging + +## Important Notes + +1. **API Rate Limits**: The framework makes many API calls. Consider Alpha Vantage Premium for production use. + +2. **Data Vendor Fallbacks**: The system has fallback logic when primary vendors fail (see `tradingagents/agents/utils/core_stock_tools.py:23-45`). + +3. **Research Disclaimer**: This framework is designed for research purposes. Trading performance varies based on LLM models, temperature, data quality, and other factors. Not intended as financial advice. + +4. **Analyst Selection**: When initializing `TradingAgentsGraph`, you can select specific analysts: + ```python + ta = TradingAgentsGraph( + selected_analysts=["market", "news", "fundamentals"], # Skip social + config=config + ) + ``` + +5. **State Logging**: All states are automatically logged to JSON files for analysis and debugging. diff --git a/main.py b/main.py index a85ee6ec..02fe0401 100644 --- a/main.py +++ b/main.py @@ -24,7 +24,7 @@ config["data_vendors"] = { ta = TradingAgentsGraph(debug=True, config=config) # forward propagate -_, decision = ta.propagate("NVDA", "2024-05-10") +_, decision = ta.propagate("XAU", "2024-05-10") print(decision) # Memorize mistakes and reflect