charieswei
/
TradingAgents
mirror of https://github.com/TauricResearch/TradingAgents.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
TradingAgents/docs/en-US/architecture_guide.md

13 KiB
Raw Blame History

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.