Enhance error handling and improve data parsing for Alpha Vantage API integration
- Implement better error handling for missing data columns - Refactor data parsing logic to ensure robustness and reliability - Update related documentation to reflect changes in data handling
This commit is contained in:
duncan
parent
32be17c606
commit
9e340c3049
|
|
@ -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.
|
||||
Loading…
Reference in New Issue