charieswei
/
TradingAgents
mirror of https://github.com/TauricResearch/TradingAgents.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
TradingAgents/PROJECT.md

20 KiB
Raw Blame History

PROJECT.md - TradingAgents Investment Platform

Multi-Agent LLM Investment Platform with Execution Capabilities Last Updated: 2025-12-26

PROJECT VISION

TradingAgents is evolving from a signal-generation research framework into a complete investment platform that:

  1. Analyzes markets using multi-agent LLM collaboration (existing capability)
  2. Executes trades via broker APIs (Alpaca, Interactive Brokers)
  3. Manages portfolios with performance tracking and Australian CGT compliance
  4. Simulates strategies to compare effectiveness before risking capital
  5. Learns from outcomes using a layered memory system (FinMem pattern)

Target Markets: US Stocks, ETFs, Crypto, Futures, Australian Equities

Patterns Borrowed From:

  • FinMem: Layered memory system (recency, relevancy, importance scoring)
  • Microsoft Qlib: Modular loose-coupled architecture
  • Alpaca Bots: Order execution, position tracking, risk controls

GOALS

Phase 1: Foundation (Current)

  • Multi-agent framework for financial analysis
  • Multiple LLM providers (OpenAI, Anthropic, Google, OpenRouter, Ollama)
  • Data vendors (yfinance, Alpha Vantage, Google News)
  • Analyst agents (fundamental, sentiment, news, technical)
  • Researcher debates (bull vs bear)
  • Risk management workflow
  • Database layer for user persistence (#2-7)
  • Enhanced data layer - FRED, multi-timeframe, benchmarks (#8-12)

Phase 2: Enhanced Analysis

  • Momentum Analyst - multi-timeframe momentum, ROC, ADX (#13)
  • Macro Analyst - FRED interpretation, regime detection (#14)
  • Correlation Analyst - cross-asset, sector rotation (#15)
  • Position Sizing Manager - Kelly, risk parity, ATR (#16)
  • Memory System - FinMem pattern for learning (#18-21)

Phase 3: Execution & Portfolio

  • Broker Integration - Alpaca (US), IBKR (futures, ASX) (#22-28)
  • Portfolio Management - positions, performance, CGT (#29-32)
  • Simulation Mode - strategy comparison without real money (#33-37)

Phase 4: Alerts & Polish

  • Alert System - Email, Slack, SMS (#38-41)
  • Backtest Engine - historical simulation (#42-44)
  • REST API - external access (#45-48)

SCOPE

In Scope

  • Multi-agent LLM analysis (fundamentals, sentiment, news, technical, momentum, macro)
  • Live trade execution via Alpaca and Interactive Brokers
  • Paper trading / simulation mode for strategy testing
  • Multi-asset support: US stocks, ETFs, crypto, futures, Australian equities
  • Portfolio tracking with mark-to-market valuation
  • Australian CGT calculations with 50% discount for >12 month holdings
  • Multi-timeframe analysis (daily, weekly, monthly)
  • Macro-economic data integration (FRED)
  • User database for profiles, portfolios, settings
  • Alert notifications (email, Slack, SMS)
  • Backtesting with historical data
  • CLI and programmatic Python interfaces
  • Optional REST API

Out of Scope

  • Mobile or web UI (API only for now)
  • Real-time streaming data (polling-based)
  • Options trading
  • Financial advice (investment decisions are user's responsibility)
  • Tax advice (CGT calculations are informational only)

CONSTRAINTS

Performance Constraints

  • API rate limits vary by data vendor (Alpha Vantage: 60 req/min with TradingAgents partnership)
  • LLM API costs scale with model choice and debate rounds
  • Memory usage scales with agent count and data volume

Technical Constraints

  • Requires Python >= 3.10
  • Requires API keys for LLM provider (OpenAI recommended)
  • Requires Alpha Vantage API key for fundamental/news data (free tier available)

Regulatory Constraints

  • Framework is NOT intended as financial, investment, or trading advice
  • For research and educational purposes only

ARCHITECTURE

System Overview (Extended)

┌─────────────────────────────────────────────────────────────────────┐
│                           DATA LAYER                                 │
├─────────────────────────────────────────────────────────────────────┤
│  yfinance │ Alpha Vantage │ FRED (NEW) │ Alpaca │ Multi-Timeframe  │
└─────────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         ANALYSIS LAYER                               │
├─────────────────────────────────────────────────────────────────────┤
│  Market  │ Momentum │  Macro   │ Correlation │ News │ Fundamentals │
│ Analyst  │ Analyst  │ Analyst  │   Analyst   │      │              │
│          │  (NEW)   │  (NEW)   │    (NEW)    │      │              │
├─────────────────────────────────────────────────────────────────────┤
│              Bull ←── Debate ──→ Bear → Research Manager            │
├─────────────────────────────────────────────────────────────────────┤
│              Trader → Signal + Confidence Score                     │
├─────────────────────────────────────────────────────────────────────┤
│         Risk Debate → Position Sizing Manager (NEW)                 │
└─────────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│                        STRATEGY LAYER (NEW)                          │
├─────────────────────────────────────────────────────────────────────┤
│  Signal-to-Order │ Position Sizing │ Timeframe Coordinator          │
└─────────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│                       EXECUTION LAYER (NEW)                          │
├─────────────────────────────────────────────────────────────────────┤
│  Order Validator │ Risk Controls │ Broker Router                    │
│                  │               │ (Paper / Alpaca / IBKR)          │
└─────────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      PORTFOLIO LAYER (NEW)                           │
├─────────────────────────────────────────────────────────────────────┤
│  Position Tracker │ Portfolio State │ Performance │ CGT Calculator  │
└─────────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    MEMORY & LEARNING (Enhanced)                      │
├─────────────────────────────────────────────────────────────────────┤
│  Layered Memory (FinMem) │ Trade History │ Risk Profiles            │
└─────────────────────────────────────────────────────────────────────┘

Broker Routing

Asset Type        →  Broker Selection
─────────────────────────────────────
US Stocks/ETFs    →  Alpaca
Crypto            →  Alpaca
Futures (GC, SI)  →  Interactive Brokers
ASX (Australia)   →  Interactive Brokers

Technology Stack

Layer Technology
Framework LangGraph, LangChain
LLM Providers OpenAI (o4-mini, gpt-4o), Anthropic, Google GenAI, OpenRouter (unified access), Ollama (local)
Data Sources yfinance, Alpha Vantage API, Reddit (PRAW)
Storage ChromaDB (vector store), Redis (caching)
CLI Rich, Questionary
Backtesting Backtrader
Python Version >= 3.10 (3.13 recommended)

Key Dependencies

  • langgraph - Agent orchestration and state management
  • langchain-openai/anthropic/google-genai - LLM integrations
  • yfinance - Stock price and technical data
  • chromadb - Vector storage for memory
  • rich - CLI output formatting

FILE ORGANIZATION

TradingAgents/
├── tradingagents/           # Main package (existing + enhanced)
│   ├── agents/
│   │   ├── analysts/        # Analyst agents
│   │   │   ├── fundamentals_analyst.py
│   │   │   ├── sentiment_analyst.py
│   │   │   ├── news_analyst.py
│   │   │   ├── market_analyst.py (technical)
│   │   │   ├── momentum_analyst.py   # NEW
│   │   │   ├── macro_analyst.py      # NEW
│   │   │   └── correlation_analyst.py # NEW
│   │   ├── managers/
│   │   │   └── position_sizing_manager.py  # NEW
│   │   └── ...
│   ├── dataflows/
│   │   ├── fred.py              # NEW - Federal Reserve data
│   │   ├── multi_timeframe.py   # NEW - Weekly/Monthly
│   │   ├── benchmark.py         # NEW - SPY, sectors
│   │   └── ...
│   └── memory/                  # NEW - FinMem pattern
│       ├── layered_memory.py
│       ├── trade_history.py
│       └── risk_profiles.py
│
├── execution/                   # NEW - Broker integration
│   ├── brokers/
│   │   ├── base.py
│   │   ├── broker_router.py
│   │   ├── alpaca_broker.py
│   │   ├── ibkr_broker.py
│   │   └── paper_broker.py
│   ├── orders/
│   └── risk_controls/
│
├── portfolio/                   # NEW - Portfolio management
│   ├── portfolio_state.py
│   ├── position_tracker.py
│   ├── performance.py
│   └── tax_calculator.py        # Australian CGT
│
├── simulation/                  # NEW - Strategy testing
│   ├── scenario_runner.py
│   ├── strategy_comparator.py
│   └── economic_conditions.py
│
├── strategy/                    # NEW
│   ├── signal_to_order.py
│   ├── position_sizing.py
│   └── strategy_executor.py
│
├── backtest/                    # NEW
│   ├── backtest_engine.py
│   └── results_analyzer.py
│
├── alerts/                      # NEW
│   ├── alert_manager.py
│   └── channels/
│
├── database/                    # NEW - User persistence
│   ├── models/
│   │   ├── user.py
│   │   ├── portfolio.py
│   │   ├── settings.py
│   │   └── trade.py
│   ├── migrations/
│   └── db.py
│
├── api/                         # NEW - REST API (optional)
│   └── app.py
│
├── cli/                         # Existing CLI
├── main.py
└── scripts/
    └── create_issues.py         # GitHub issue creation

TESTING STRATEGY

Test Organization (REQUIRED)

All new code MUST include tests organized as follows:

tests/
├── conftest.py              # Shared fixtures (LLM mocks, env mocks)
├── unit/                    # Fast, mocked tests
│   ├── conftest.py         # Unit-specific fixtures
│   └── test_*.py
├── integration/             # Tests with real internal components
│   ├── conftest.py         # Integration fixtures
│   └── test_*.py
└── e2e/                     # End-to-end tests
    └── test_*.py

Testing Requirements

  1. TDD Approach: Write tests BEFORE implementation
  2. Unit Tests: All new functions must have unit tests
  3. Integration Tests: All new features must have integration tests
  4. Mocking: Use fixtures in conftest.py for LLM and API mocking
  5. Markers: Use @pytest.mark.unit, @pytest.mark.integration, @pytest.mark.e2e

Test Fixtures (conftest.py)

Standard fixtures that MUST be used:

  • mock_env_openrouter, mock_env_openai, mock_env_anthropic - Environment isolation
  • mock_langchain_classes - LLM class mocking
  • mock_chromadb - Database mocking (uses get_or_create_collection)
  • mock_yfinance, mock_alpha_vantage - Data vendor mocking

Running Tests

pytest tests/unit -m unit           # Fast unit tests only
pytest tests/integration -m integration  # Integration tests
pytest tests/ --tb=short           # All tests

DOCUMENTATION MAP

Document Purpose
README.md Installation, usage, API reference, feature overview
PROJECT.md This file - project roadmap, architecture, configuration
LICENSE MIT License
docs/ Comprehensive documentation structure (see below)
assets/ Architecture diagrams, CLI screenshots

Documentation Structure (docs/)

Located in /docs/ directory with the following sections:

  • Getting Started

    • QUICKSTART.md - Get up and running with TradingAgents
    • development/setup.md - Development environment setup
    • guides/configuration.md - Configuration reference for LLM providers and data vendors

  • Architecture & Design

    • architecture/multi-agent-system.md - Agent roles and collaboration patterns
    • architecture/data-flow.md - System data flow and integrations
    • architecture/llm-integration.md - LLM provider abstraction and selection

  • API Reference

    • api/trading-graph.md - Core TradingGraph orchestration API
    • api/agents.md - Agent interfaces and implementations
    • api/dataflows.md - Data vendor integrations and APIs

  • Developer Guides

    • guides/adding-new-analyst.md - Extend framework with custom analysts
    • guides/adding-llm-provider.md - Integrate new LLM providers
    • guides/adding-data-vendor.md - Add new data vendor integrations

  • Testing

    • testing/README.md - Testing philosophy and overview
    • testing/running-tests.md - Test suite execution guide
    • testing/writing-tests.md - Guidelines for writing new tests

  • Development

    • development/setup.md - Development environment configuration
    • development/contributing.md - Contributing guidelines

For full documentation index, see docs/README.md

CURRENT SPRINT

Sprint: Platform Foundation

Goal: Build the foundation for the investment platform

Active Work

See GitHub Issues for full backlog.

Phase 1: Database (Issues #2-7)

  • #2 Database setup - SQLAlchemy + PostgreSQL/SQLite
  • #3 User model - profiles, tax jurisdiction
  • #4 Portfolio model - live, paper, backtest
  • #5 Settings model - risk profiles, alerts
  • #6 Trade model - CGT tracking
  • #7 Alembic migrations

Phase 2: Data Layer (Issues #8-12)

  • #8 FRED API integration
  • #9 Multi-timeframe aggregation
  • #10 Benchmark data
  • #11 Interface routing
  • #12 Data caching

Backlog (47 total issues)

  • Phase 3: New Analysts (#13-17)
  • Phase 4: Memory System (#18-21)
  • Phase 5: Execution Layer (#22-28)
  • Phase 6: Portfolio Management (#29-32)
  • Phase 7: Simulation (#33-37)
  • Phase 8: Alerts (#38-41)
  • Phase 9: Backtest (#42-44)
  • Phase 10: API & Docs (#45-48)

CONFIGURATION REFERENCE

Environment Variables

# LLM Provider API Keys (choose one based on llm_provider config)
OPENAI_API_KEY=<optional>           # OpenAI API key (required for OpenAI provider or embeddings)
ANTHROPIC_API_KEY=<optional>        # Anthropic API key (required for Anthropic provider)
OPENROUTER_API_KEY=<optional>       # OpenRouter API key (required for OpenRouter provider)
GOOGLE_API_KEY=<optional>           # Google API key (required for Google provider)

# Data Vendor API Keys
ALPHA_VANTAGE_API_KEY=<required>    # Alpha Vantage for fundamental/news data

# Application Configuration
TRADINGAGENTS_RESULTS_DIR=./results # Output directory for results

Default Config Options

{
    "llm_provider": "openai",        # Options: openai, anthropic, google, openrouter, ollama
    "deep_think_llm": "o4-mini",     # For complex reasoning
    "quick_think_llm": "gpt-4o-mini", # For fast responses
    "backend_url": "https://api.openai.com/v1",  # API endpoint (varies by provider)
    "max_debate_rounds": 1,
    "max_risk_discuss_rounds": 1,
    "data_vendors": {
        "core_stock_apis": "yfinance",
        "technical_indicators": "yfinance",
        "fundamental_data": "alpha_vantage",
        "news_data": "alpha_vantage",
    }
}

OpenRouter Configuration Example

OpenRouter provides unified access to multiple LLM models. To use OpenRouter:

config = {
    "llm_provider": "openrouter",
    "deep_think_llm": "anthropic/claude-sonnet-4.5",  # provider/model-name format
    "quick_think_llm": "openai/gpt-4o-mini",
    "backend_url": "https://openrouter.ai/api/v1",
}

Requirements:

  • OPENROUTER_API_KEY environment variable must be set
  • OPENAI_API_KEY must also be set for embeddings (OpenRouter does not provide embeddings)
  • Model names use the format: provider/model-name (e.g., anthropic/claude-sonnet-4.5, openai/gpt-4o)
  • See OpenRouter models list for available models

DEVELOPMENT NOTES

Getting Started

# Clone and setup
git clone https://github.com/TauricResearch/TradingAgents.git
cd TradingAgents
conda create -n tradingagents python=3.13
conda activate tradingagents
pip install -r requirements.txt

# Configure API keys
export OPENAI_API_KEY=your_key
export ALPHA_VANTAGE_API_KEY=your_key

# Run CLI
python -m cli.main

# Or use programmatically
python main.py

Key Entry Points

  • python -m cli.main - Interactive CLI
  • python main.py - Programmatic example
  • TradingAgentsGraph.propagate(ticker, date) - Core API

Generated by autonomous-dev setup wizard