⚡ When.Trade

AI-Powered Multi-Agent Investment Analysis Platform

Intelligent market analysis through collaborative AI agents • Inspired by TradingAgents

🇺🇸 English | 🇨🇳 中文

📋 Table of Contents

• ✨ Overview
• 🚀 Key Features
• 🏗️ Architecture
• 💻 Tech Stack
• ⚡ Quick Start
• 📸 Screenshots
• 📖 Usage Examples
• 🏢 Project Structure
• ⭐ Star History
• 🙏 Acknowledgments
• 📄 License

✨ Overview

When.Trade is an open-source AI-powered investment analysis platform that revolutionizes market analysis through intelligent multi-agent collaboration.

Building upon the innovative foundation laid by TradingAgents, this project implements a sophisticated ecosystem where specialized AI agents work together to:

• 🔍 Analyze complex market data from multiple sources
• 💭 Debate investment strategies through Bull vs Bear perspectives
• ⚖️ Assess comprehensive risk scenarios
• 📊 Generate actionable investment recommendations

🚀 Key Features

Feature	Description	Benefits
⚡ Real-time Analysis	WebSocket-based live data streaming and instant results	Up-to-the-minute market insights
🧠 Multiple LLM Support	OpenAI, Anthropic, DeepSeek, Kimi, and other providers	Flexibility and redundancy in AI reasoning
📊 Unified Data Interface	Integrated multiple data sources with automatic failover	Reliable data access and consistency
🎯 Advanced Risk Management	Multi-perspective risk assessment and scenario analysis	Enhanced portfolio protection
🔄 LangGraph Orchestration	Complex analysis workflows managed through state graphs	Scalable and maintainable agent coordination

🏗️ Architecture

System Overview

graph TB
    subgraph "Frontend Layer"
        UI[🖥️ Vue.js 3 + TypeScript]
        WS[🔌 WebSocket Client]
        ST[📦 Pinia State Management]
    end

    subgraph "Backend API Layer"
        API[⚡ FastAPI Server]
        WSS[🔌 WebSocket Server]
        RT[📊 Real-time Engine]
    end

    subgraph "Multi-Agent System"
        GRAPH[🎭 LangGraph Orchestrator]

        subgraph "Analysis Agents"
            MA[📈 Market Analyst]
            NA[📰 News Analyst]
            SA[💬 Social Analyst]
        end

        subgraph "Research Agents"
            BR[🐂 Bull Researcher]
            BEAR[🐻 Bear Researcher]
        end

        subgraph "Decision Agents"
            TR[💰 Trader]
            RM[⚖️ Risk Manager]
            PM[📋 Portfolio Manager]
        end
    end

    subgraph "Data Layer"
        DB[(🗄️ PostgreSQL)]
        REDIS[(⚡ Redis Cache)]
        EXT[🌐 External APIs]
    end

    UI --> API
    WS --> WSS
    API --> GRAPH
    WSS --> RT
    GRAPH --> MA
    GRAPH --> NA
    GRAPH --> SA
    GRAPH --> BR
    GRAPH --> BEAR
    GRAPH --> TR
    GRAPH --> RM
    GRAPH --> PM
    API --> DB
    API --> REDIS
    API --> EXT

Loading

Four-Layer Architecture

graph LR
    subgraph "🎨 UI Layer"
        C[Components]
        V[Views]
        S[Stores]
    end

    subgraph "⚙️ Service Layer"
        BL[Business Logic]
        WF[Workflows]
        VA[Validation]
    end

    subgraph "🔌 Adapter Layer"
        LLM[LLM Adapters]
        API_A[API Adapters]
        DATA[Data Adapters]
    end

    subgraph "🔧 Port Layer"
        INTF[Interfaces]
        CONT[Contracts]
        TYPES[Types]
    end

    C --> BL
    V --> BL
    S --> BL
    BL --> LLM
    WF --> API_A
    VA --> DATA
    LLM --> INTF
    API_A --> CONT
    DATA --> TYPES

Loading

Multi-Agent Workflow

sequenceDiagram
    participant User
    participant WebSocket
    participant Orchestrator
    participant DataAgents
    participant ResearchAgents
    participant DecisionAgents

    User->>WebSocket: Start Analysis Request
    WebSocket->>Orchestrator: Initialize Analysis

    Note over Orchestrator: Phase 1: Data Collection
    Orchestrator->>DataAgents: Gather Market Data
    DataAgents-->>Orchestrator: Analysis Results

    Note over Orchestrator: Phase 2: Investment Debate
    Orchestrator->>ResearchAgents: Bull vs Bear Debate
    ResearchAgents-->>Orchestrator: Debate Conclusions

    Note over Orchestrator: Phase 3: Decision Making
    Orchestrator->>DecisionAgents: Risk & Portfolio Analysis
    DecisionAgents-->>Orchestrator: Final Recommendations

    Orchestrator->>WebSocket: Stream Results
    WebSocket->>User: Real-time Updates

Loading

💻 Tech Stack

🐍 Backend Technologies

Category	Technology	Version	Purpose
🚀 Framework	FastAPI	0.109+	High-performance async API
🧠 AI/ML	LangChain + LangGraph	Latest	Multi-agent orchestration
🗄️ Database	PostgreSQL	15+	Primary data storage
⚡ Cache	Redis	7+	High-speed caching
🔄 Queue	Celery	5.3+	Background task processing
🧪 Testing	pytest	7.4+	Comprehensive testing suite

🎨 Frontend Technologies

Category	Technology	Version	Purpose
⚛️ Framework	Vue.js	3.3+	Reactive user interface
📘 Language	TypeScript	5.6+	Type-safe development
⚡ Build Tool	Vite	7.0+	Fast development and builds
🎨 Styling	Tailwind CSS	Latest	Utility-first CSS framework
📊 State	Pinia	Latest	Type-safe state management
📈 Charts	Chart.js	4.4+	Financial data visualization

🤖 LLM Integrations

Provider	Models	Features
🤖 OpenAI	GPT-4, GPT-3.5-turbo	Tool calling, reasoning
🌐 Google	Gemini Pro, Gemini	Multimodal, efficient reasoning
🇨🇳 DeepSeek	DeepSeek	High performance, cost-effective
🌙 Kimi	Moonshot-Kimi	Real-time data processing

⚡ Quick Start

Prerequisites

📋 System Requirements

Component	Minimum	Recommended
Python	3.9+	3.11+
Node.js	16+	18+
PostgreSQL	15+	16+
Redis	7+	7+

🛠️ Manual Installation

1️⃣ Clone Repository

git clone https://github.com/foldedcode/when.trade.git
cd when.trade

2️⃣ Backend Setup

# Create conda environment
conda create -n whentrade python=3.11
conda activate whentrade

# Install dependencies
pip install -r requirements.txt

# Setup database
createdb whentrade_new
alembic upgrade head

3️⃣ Frontend Setup

cd web
npm install
# or use yarn
yarn install

4️⃣ Environment Configuration

# Copy environment template
cp .env.example .env

# Edit configuration (required)
nano .env  # Add your API keys and database settings

Optional API Keys (Configure based on your needs):

• OPENAI_API_KEY - Get from OpenAI
• DEEPSEEK_API_KEY - Get from DeepSeek
• KIMI_API_KEY - Get from Kimi (Moonshot AI)
• GOOGLE_API_KEY - Get from Google AI Studio
• FINNHUB_API_KEY - Get from Finnhub
• COINGECKO_API_KEY - Get from CoinGecko
• REDDIT_CLIENT_ID & REDDIT_CLIENT_SECRET - Get from Reddit Apps

🚀 Launch Application

Option 1: Using Start Scripts

# Start backend
./start.sh

# Start frontend (new terminal)
cd web && npm run dev

Option 2: Manual Start

# Terminal 1: Backend
conda activate whentrade
uvicorn core.main:app --reload --host 0.0.0.0 --port 8000

# Terminal 2: Frontend
cd web
npm run dev

Option 3: Production Mode

# Build and start production
npm run build
python -m uvicorn core.main:app --host 0.0.0.0 --port 8000

🔗 Access Points

Service	URL	Description
🖥️ Frontend	http://localhost:3000	Main application interface
📡 API Server	http://localhost:8000	Backend API endpoint
📚 API Docs	http://localhost:8000/docs	Interactive API documentation
🔍 API Redoc	http://localhost:8000/redoc	Alternative API documentation

✅ Verification

# Check backend health
curl http://localhost:8000/health

# Check WebSocket connection
wscat -c ws://localhost:8000/ws/analysis

# Run tests
pytest  # Backend tests
npm test  # Frontend tests

📸 Screenshots

🖥️ Product Interface

🎬 Product Features

Real-time Multi-Agent Analysis - Collaborative AI agents working together Professional Investment Insights - Bull vs Bear research debates Comprehensive Risk Assessment - Multi-perspective scenario analysis Modern Web Interface - Vue.js 3 with responsive design

🏢 Project Structure

when.trade/                         # 📁 Project Root
├── 🐍 core/                        # Backend Application
│   ├── 🤖 agents/                  # Multi-Agent System
│   │   ├── 📄 base.py              # Agent Base Classes (⚠️ 1,344 lines)
│   │   ├── 📊 analysts/            # Market Analysis Agents
│   │   │   ├── market_analyst.py   # Technical & Price Analysis
│   │   │   ├── news_analyst.py     # News Sentiment Analysis
│   │   │   └── fundamentals_analyst.py # Fundamental Analysis
│   │   ├── 🔬 researchers/         # Investment Research Agents
│   │   │   ├── bull_researcher.py  # Bullish Case Research
│   │   │   └── bear_researcher.py  # Bearish Case Research
│   │   ├── 👥 managers/            # Management Agents
│   │   │   ├── research_manager.py # Research Coordination
│   │   │   ├── risk_manager.py     # Risk Assessment
│   │   │   └── portfolio_manager.py # Portfolio Management
│   │   ├── ⚖️ risk_mgmt/           # Risk Management Agents
│   │   ├── 🧰 utils/               # Agent Utilities (⚠️ 1,602 lines)
│   │   └── 🏭 factory.py           # Dynamic Agent Factory
│   ├── 🌐 api/                     # API Layer
│   │   └── v1/routes/              # API Routes
│   │       ├── analysis_ws.py      # WebSocket Handler (⚠️ 2,510 lines)
│   │       ├── analysis.py         # Analysis REST API
│   │       └── agents.py           # Agent Management API
│   ├── 🔄 services/                # Business Logic Layer
│   ├── 🔌 adapters/                # External Integrations
│   │   ├── llm_adapters/           # LLM Provider Adapters
│   │   ├── data_adapters/          # Market Data Adapters
│   │   └── api_adapters/           # External API Adapters
│   ├── 📊 dataflows/               # Data Processing Layer
│   │   ├── interface.py            # Unified Data Interface (⚠️ 1,624 lines)
│   │   └── realtime_news_utils.py  # Real-time News Processing
│   ├── 🎭 graph/                   # LangGraph Orchestration
│   │   └── whentrade_graph.py      # Main Workflow Graph
│   ├── 🗄️ database/               # Database Layer
│   ├── ⚙️ config/                  # Configuration Management
│   └── 📄 main.py                  # FastAPI Application Entry
│
├── 🎨 web/                         # Frontend Application (197 files)
│   ├── src/
│   │   ├── 🧩 components/          # Vue.js Components
│   │   │   ├── analysis/           # Analysis Interface Components
│   │   │   └── common/             # Reusable Components
│   │   ├── 📦 stores/              # Pinia State Management
│   │   │   ├── analysis.ts         # Analysis State
│   │   │   ├── agents.ts           # Agent State
│   │   │   └── websocket.ts        # WebSocket State
│   │   ├── 🔧 services/            # Frontend Business Logic
│   │   ├── 🔌 adapters/            # Frontend API Adapters
│   │   ├── 🎨 assets/              # Static Assets
│   │   └── 📱 views/               # Page Views
│   ├── 📦 package.json             # Node.js Dependencies
│   └── ⚙️ vite.config.ts           # Vite Configuration
│
├── ⚙️ configs/                     # Configuration Files
├── 🚀 scripts/                     # Deployment & Utility Scripts
├── 📚 docs/                        # Documentation
│   ├── images/                     # README Images & Screenshots
│   └── diagrams/                   # Architecture Diagrams
├── 🧪 tests/                       # Test Suites
├── 🗃️ alembic/                     # Database Migrations
└── 📄 README.md                    # Project Documentation

📊 Key Metrics

Category	Count	Notes
Python Files	150+	Backend implementation
TypeScript Files	197	Frontend implementation
Total Lines of Code	50,000+	Estimated project size
Large Files	6	Files >1,000 lines (see warnings)
Test Coverage	80%+	Comprehensive test suite

⚠️ Large File Navigation

For optimal development experience, use symbol-based navigation for these files:

File	Lines	Navigation Strategy
agents/base.py	1,344	Use class-based navigation
agents/utils/agent_utils.py	1,602	Use function-based search
api/v1/routes/analysis_ws.py	2,510	Use endpoint-based navigation
dataflows/interface.py	1,624	Use method-based search

⭐ Star History

🙏 Acknowledgments

🎯 Core Inspiration

TradingAgents - The pioneering project that inspired our multi-agent approach to financial analysis.

🛠️ Technology Partners

Technology	Contribution
LangChain	Multi-agent orchestration framework
FastAPI	High-performance async web framework
Vue.js	Reactive frontend framework
PostgreSQL	Robust database system
Redis	High-speed caching solution

📢 Disclaimer

⚠️ Important: This software is for educational and research purposes only.

• Do not use for actual trading without proper risk management
• Perform thorough due diligence before any investment decisions
• Past performance does not guarantee future results
• Authors are not responsible for any financial losses

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Built with ❤️ by the When.Trade community

⭐ Star us on GitHub • 🐛 Report Issues • 🤝 Contribute