377 lines
13 KiB
Markdown
377 lines
13 KiB
Markdown
# TradingAgents System Architecture Guide
|
|
|
|
## 📖 Overview
|
|
|
|
This document provides a comprehensive overview of the TradingAgents system architecture, including the integration of Chinese market features, database systems, and multi-LLM support. The architecture is designed for scalability, reliability, and global market coverage.
|
|
|
|
## 🏗️ High-Level Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ TradingAgents System │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ CLI Interface (Market Selection + Configuration) │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ Multi-Agent Framework │
|
|
│ ├── Market Analyst ├── Fundamentals Analyst │
|
|
│ ├── News Analyst ├── Bull/Bear Researchers │
|
|
│ └── Trader Agent └── Risk Management │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ Multi-LLM Provider Layer │
|
|
│ ├── DashScope (Qwen) ├── OpenAI (GPT) │
|
|
│ ├── Google (Gemini) └── Anthropic (Claude) │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ Data Layer │
|
|
│ ├── US Market (Yahoo Finance) │
|
|
│ ├── China A-Share (TongDaXin API) │
|
|
│ └── Financial News & Social Media │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ Caching & Storage Layer │
|
|
│ ├── MongoDB (Persistent Storage) │
|
|
│ ├── Redis (High-Performance Cache) │
|
|
│ └── File Cache (Fallback) │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## 🎯 Core Components
|
|
|
|
### 1. CLI Interface Layer
|
|
|
|
#### Market Selection System
|
|
- **Interactive Market Selection**: US Stock vs China A-Share
|
|
- **Format Validation**: Market-specific ticker validation
|
|
- **Data Source Routing**: Automatic routing based on market selection
|
|
- **English-Only Interface**: Internationalization-ready
|
|
|
|
**Key Files**:
|
|
```
|
|
cli/main.py - Main CLI application
|
|
cli/utils.py - Market selection and validation utilities
|
|
```
|
|
|
|
**Flow**:
|
|
```
|
|
User Input → Market Selection → Ticker Validation → Data Source Assignment
|
|
```
|
|
|
|
### 2. Multi-Agent Framework
|
|
|
|
#### Agent Hierarchy
|
|
```
|
|
TradingAgentsGraph
|
|
├── Analyst Team
|
|
│ ├── MarketAnalyst (Technical Analysis)
|
|
│ ├── FundamentalsAnalyst (Financial Analysis)
|
|
│ └── NewsAnalyst (Sentiment Analysis)
|
|
├── Research Team
|
|
│ ├── BullResearcher (Positive Sentiment)
|
|
│ └── BearResearcher (Risk Analysis)
|
|
├── Trading Team
|
|
│ ├── TraderAgent (Decision Making)
|
|
│ └── RiskManager (Risk Assessment)
|
|
└── Reflection System
|
|
└── ReflectionAgent (Quality Control)
|
|
```
|
|
|
|
**Key Files**:
|
|
```
|
|
tradingagents/graph/trading_graph.py - Main agent orchestration
|
|
tradingagents/agents/analysts/ - Analyst implementations
|
|
tradingagents/agents/researchers/ - Research team
|
|
tradingagents/agents/trader/ - Trading decisions
|
|
```
|
|
|
|
### 3. Multi-LLM Provider Layer
|
|
|
|
#### Provider Architecture
|
|
```
|
|
LLM Request → Provider Router → Specific Adapter → API Call → Response
|
|
```
|
|
|
|
#### Supported Providers
|
|
1. **DashScope (Alibaba Cloud)**
|
|
- Models: qwen-turbo, qwen-plus, qwen-max, qwen-max-longcontext
|
|
- Optimized for Chinese language
|
|
- Primary choice for Chinese users
|
|
|
|
2. **OpenAI**
|
|
- Models: GPT-4o, GPT-4o-mini, o1, o3, o4-mini
|
|
- Global standard for English content
|
|
|
|
3. **Google AI**
|
|
- Models: Gemini 2.0 Flash, Gemini 2.5 Flash
|
|
- Advanced reasoning capabilities
|
|
|
|
4. **Anthropic**
|
|
- Models: Claude 3.5 Haiku, Claude 3.5 Sonnet, Claude 4
|
|
- Strong analytical capabilities
|
|
|
|
**Key Files**:
|
|
```
|
|
tradingagents/graph/trading_graph.py - LLM initialization
|
|
tradingagents/agents/utils/memory.py - Embedding services
|
|
cli/utils.py - Provider selection
|
|
```
|
|
|
|
#### Intelligent Fallback System
|
|
```
|
|
Primary Provider (DashScope)
|
|
↓ (if unavailable)
|
|
Secondary Provider (OpenAI)
|
|
↓ (if unavailable)
|
|
Tertiary Provider (Google/Anthropic)
|
|
↓ (if all fail)
|
|
Error Handling & User Notification
|
|
```
|
|
|
|
### 4. Data Layer Architecture
|
|
|
|
#### Multi-Market Data Sources
|
|
|
|
**US Stock Market**:
|
|
```
|
|
Yahoo Finance API → Data Validation → Cache Storage → Agent Consumption
|
|
```
|
|
|
|
**China A-Share Market**:
|
|
```
|
|
TongDaXin API → Data Optimization → Cache Storage → Agent Consumption
|
|
```
|
|
|
|
#### Data Flow Architecture
|
|
```
|
|
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
|
│ Data Request │ -> │ Source Router │ -> │ Data Provider │
|
|
└─────────────────┘ └──────────────────┘ └─────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
|
│ Cache Manager │ <- │ Data Processor │ <- │ Raw Data │
|
|
└─────────────────┘ └──────────────────┘ └─────────────────┘
|
|
```
|
|
|
|
**Key Files**:
|
|
```
|
|
tradingagents/dataflows/interface.py - Data interface
|
|
tradingagents/dataflows/tdx_utils.py - TongDaXin integration
|
|
tradingagents/dataflows/optimized_china_data.py - China data optimization
|
|
tradingagents/dataflows/chinese_finance_utils.py - Chinese finance tools
|
|
tradingagents/dataflows/stock_data_service.py - Unified data service
|
|
```
|
|
|
|
#### Supported Chinese Exchanges
|
|
- **Shanghai Stock Exchange**: 60xxxx (e.g., 600036 - China Merchants Bank)
|
|
- **Shenzhen Stock Exchange**: 00xxxx (e.g., 000001 - Ping An Bank)
|
|
- **ChiNext Board**: 30xxxx (e.g., 300001 - Technology stocks)
|
|
- **STAR Market**: 68xxxx (e.g., 688001 - Innovation companies)
|
|
|
|
### 5. Caching & Storage Layer
|
|
|
|
#### Three-Tier Cache Architecture
|
|
|
|
**Tier 1: Redis (High-Performance Cache)**
|
|
```
|
|
Memory-based → Sub-millisecond access → Real-time data
|
|
```
|
|
|
|
**Tier 2: MongoDB (Persistent Storage)**
|
|
```
|
|
Document-based → Structured storage → Historical data & analytics
|
|
```
|
|
|
|
**Tier 3: File Cache (Fallback)**
|
|
```
|
|
File-based → Reliable fallback → Always available
|
|
```
|
|
|
|
#### Cache Management Flow
|
|
```
|
|
Data Request
|
|
↓
|
|
Redis Check (Tier 1)
|
|
↓ (if miss)
|
|
MongoDB Check (Tier 2)
|
|
↓ (if miss)
|
|
File Cache Check (Tier 3)
|
|
↓ (if miss)
|
|
External API Call
|
|
↓
|
|
Store in All Tiers
|
|
```
|
|
|
|
**Key Files**:
|
|
```
|
|
tradingagents/dataflows/cache_manager.py - Cache coordination
|
|
tradingagents/dataflows/db_cache_manager.py - Database cache
|
|
tradingagents/dataflows/integrated_cache.py - Integrated cache system
|
|
tradingagents/dataflows/adaptive_cache.py - Adaptive cache strategies
|
|
tradingagents/config/database_manager.py - Database connections
|
|
tradingagents/config/mongodb_storage.py - MongoDB operations
|
|
```
|
|
|
|
#### Database Schema Design
|
|
|
|
**MongoDB Collections**:
|
|
```
|
|
stock_data - Historical stock prices and volumes
|
|
analysis_results - Agent analysis outputs
|
|
token_usage - LLM API usage tracking
|
|
cache_metadata - Cache management information
|
|
user_sessions - User interaction history
|
|
```
|
|
|
|
**Redis Key Patterns**:
|
|
```
|
|
stock:{symbol}:{date} - Daily stock data
|
|
analysis:{symbol}:{timestamp} - Analysis results
|
|
news:{symbol}:{date} - News sentiment data
|
|
cache:meta:{key} - Cache metadata
|
|
```
|
|
|
|
## 🔄 Data Flow Patterns
|
|
|
|
### 1. Analysis Workflow
|
|
```
|
|
User Input (CLI)
|
|
↓
|
|
Market Selection & Validation
|
|
↓
|
|
Data Retrieval (Multi-source)
|
|
↓
|
|
Agent Analysis (Multi-LLM)
|
|
↓
|
|
Result Aggregation
|
|
↓
|
|
Output Generation
|
|
↓
|
|
Cache Storage
|
|
```
|
|
|
|
### 2. Cache Workflow
|
|
```
|
|
Data Request
|
|
↓
|
|
Cache Key Generation
|
|
↓
|
|
Tier 1 (Redis) Check
|
|
↓ (if miss)
|
|
Tier 2 (MongoDB) Check
|
|
↓ (if miss)
|
|
Tier 3 (File) Check
|
|
↓ (if miss)
|
|
External API Call
|
|
↓
|
|
Multi-tier Storage
|
|
↓
|
|
Response to User
|
|
```
|
|
|
|
### 3. Error Handling Workflow
|
|
```
|
|
Component Failure
|
|
↓
|
|
Error Detection
|
|
↓
|
|
Fallback Activation
|
|
↓
|
|
Alternative Path
|
|
↓
|
|
User Notification (if needed)
|
|
↓
|
|
Graceful Degradation
|
|
```
|
|
|
|
## 🛡️ Reliability & Scalability Features
|
|
|
|
### High Availability Design
|
|
- **Multi-LLM Fallback**: Automatic provider switching
|
|
- **Multi-tier Caching**: Redundant data storage
|
|
- **Graceful Degradation**: System continues with reduced functionality
|
|
- **Error Recovery**: Automatic retry mechanisms
|
|
|
|
### Scalability Features
|
|
- **Database Clustering**: MongoDB replica sets
|
|
- **Cache Scaling**: Redis clustering support
|
|
- **Load Balancing**: Multiple API endpoints
|
|
- **Horizontal Scaling**: Stateless agent design
|
|
|
|
### Performance Optimization
|
|
- **Intelligent Caching**: Adaptive cache strategies
|
|
- **Connection Pooling**: Database connection management
|
|
- **Async Processing**: Non-blocking operations
|
|
- **Data Compression**: Efficient storage formats
|
|
|
|
## 🔧 Configuration Management
|
|
|
|
### Environment-Based Configuration
|
|
```
|
|
.env File → Environment Variables → Runtime Configuration
|
|
```
|
|
|
|
### Configuration Hierarchy
|
|
```
|
|
1. Environment Variables (.env)
|
|
2. Default Configuration (default_config.py)
|
|
3. Runtime Overrides (main.py)
|
|
4. Dynamic Configuration (config.py)
|
|
```
|
|
|
|
### Configuration Categories
|
|
- **API Keys**: LLM providers and data sources
|
|
- **Database Settings**: MongoDB and Redis configuration
|
|
- **Cache Settings**: Cache TTL and strategies
|
|
- **Market Settings**: Supported markets and exchanges
|
|
- **Agent Settings**: Model selection and parameters
|
|
|
|
## 📊 Monitoring & Analytics
|
|
|
|
### System Metrics
|
|
- **API Usage**: Token consumption and costs
|
|
- **Cache Performance**: Hit rates and response times
|
|
- **Database Performance**: Query times and storage usage
|
|
- **Error Rates**: Failure rates by component
|
|
|
|
### Business Metrics
|
|
- **Analysis Quality**: Agent performance metrics
|
|
- **User Engagement**: Usage patterns and preferences
|
|
- **Market Coverage**: Supported symbols and exchanges
|
|
- **Response Times**: End-to-end analysis duration
|
|
|
|
## 🚀 Deployment Architecture
|
|
|
|
### Development Environment
|
|
```
|
|
Local Machine → File Cache → Single LLM Provider → Basic Features
|
|
```
|
|
|
|
### Production Environment
|
|
```
|
|
Application Server → Redis Cluster → MongoDB Replica Set → Multi-LLM → Full Features
|
|
```
|
|
|
|
### Cloud Deployment Options
|
|
- **Database**: MongoDB Atlas, Redis Cloud
|
|
- **Application**: Docker containers, Kubernetes
|
|
- **Load Balancing**: Application load balancers
|
|
- **Monitoring**: Application performance monitoring
|
|
|
|
## 🔮 Future Architecture Enhancements
|
|
|
|
### Planned Improvements
|
|
- **Microservices Architecture**: Service decomposition
|
|
- **Event-Driven Architecture**: Async message processing
|
|
- **Machine Learning Pipeline**: Automated model training
|
|
- **Real-time Streaming**: Live market data processing
|
|
- **Global CDN**: Distributed cache network
|
|
|
|
### Extensibility Points
|
|
- **New Market Support**: Additional exchanges and regions
|
|
- **New LLM Providers**: Additional AI services
|
|
- **Custom Agents**: User-defined analysis agents
|
|
- **Plugin System**: Third-party integrations
|
|
- **API Gateway**: External service access
|
|
|
|
---
|
|
|
|
This architecture provides a robust, scalable foundation for global financial market analysis while maintaining flexibility for future enhancements and integrations.
|