mirror of https://github.com/Xe138/AI-Trader.git synced 2026-04-01 17:17:24 -04:00

Files

Bill 0e739a9720 Merge rebrand from AI-Trader to AI-Trader-Server

Complete rebrand of project to reflect REST API service architecture:
- Updated all documentation (README, guides, API reference)
- Updated Docker configuration (compose, Dockerfile, images)
- Updated all repository URLs to Xe138/AI-Trader-Server
- Updated all Docker images to ghcr.io/xe138/ai-trader-server
- Added fork acknowledgment crediting HKUDS/AI-Trader
- Updated GitHub Actions workflows and shell scripts

All 4 phases completed with validation checkpoints.

Co-Authored-By: Claude <noreply@anthropic.com>

2025-11-01 12:11:34 -04:00

17 KiB

Raw Permalink Blame History

🚀 AI-Trader-Server: REST API for AI Trading

REST API service for autonomous AI trading competitions. Run multiple AI models in NASDAQ 100 trading simulations with zero human intervention.

🚀 Quick Start • 📚 API Reference • 📖 Documentation

🌟 What is AI-Trader-Server?

AI-Trader-Server enables multiple AI models to compete autonomously in NASDAQ 100 trading, making 100% independent decisions through a standardized tool-based architecture.

Key Features

🤖 Fully Autonomous Trading - AI agents analyze, decide, and execute without human intervention
🌐 REST API Architecture - Trigger simulations and monitor results via HTTP
🛠️ MCP Toolchain - Standardized tools for market research, price queries, and trade execution
🏆 Multi-Model Competition - Deploy GPT, Claude, Qwen, DeepSeek, or custom models
📊 Real-Time Analytics - Track positions, P&L, and AI decision reasoning
⏰ Historical Replay - Backtest with anti-look-ahead controls
💾 Persistent Storage - SQLite database for all results and analytics
🔌 External Orchestration - Integrate with any HTTP client or workflow automation service

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                     REST API (Port 8080)                    │
│  POST /simulate/trigger  │  GET /status  │  GET /results   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   Simulation Worker                         │
│  • Job Manager (concurrent job prevention)                  │
│  • Date-sequential, model-parallel execution                │
│  • Isolated runtime configs per model-day                   │
└─────────────────────────────────────────────────────────────┘
                              │
                ┌─────────────┴─────────────┐
                ▼                           ▼
┌───────────────────────────┐   ┌──────────────────────────┐
│   AI Agent (Model-Day)    │   │   SQLite Database        │
│  • GPT-4, Claude, etc.    │   │  • Jobs & Details        │
│  • MCP Tool Access        │   │  • Positions & Holdings  │
│  • Decision Logging       │   │  • Reasoning Logs        │
└───────────────────────────┘   └──────────────────────────┘
                │
                ▼
┌─────────────────────────────────────────────────────────────┐
│                  MCP Services (Internal)                    │
│  • Math (8000)  • Search (8001)  • Trade (8002)            │
│  • Price (8003) - All localhost-only                        │
└─────────────────────────────────────────────────────────────┘

🚀 Quick Start

Docker Deployment (5 minutes)

1. Prerequisites

Docker and Docker Compose installed
API keys: OpenAI, Alpha Vantage, Jina AI

2. Setup

git clone https://github.com/Xe138/AI-Trader-Server.git
cd AI-Trader-Server

# Configure environment
cp .env.example .env
# Edit .env and add your API keys

3. Start Service

docker-compose up -d

# Verify health
curl http://localhost:8080/health

4. Run Simulation

curl -X POST http://localhost:8080/simulate/trigger \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2025-01-16",
    "models": ["gpt-4"]
  }'

5. Monitor Progress

# Use job_id from trigger response
curl http://localhost:8080/simulate/status/{job_id}

6. View Results

curl "http://localhost:8080/results?job_id={job_id}"

📖 Detailed guide: QUICK_START.md

📚 API Overview

Endpoints

Endpoint	Method	Purpose
`/simulate/trigger`	POST	Start simulation job
`/simulate/status/{job_id}`	GET	Check job progress
`/results`	GET	Query trading results
`/health`	GET	Service health check

Example: Trigger Simulation

Request:

curl -X POST http://localhost:8080/simulate/trigger \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2025-01-16",
    "end_date": "2025-01-17",
    "models": ["gpt-4", "claude-3.7-sonnet"]
  }'

Response:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "total_model_days": 4,
  "message": "Simulation job created with 2 trading dates"
}

Parameters:

start_date (required) - Start date in YYYY-MM-DD format
end_date (optional) - End date, defaults to start_date for single-day simulation
models (optional) - Model signatures to run, defaults to all enabled models in config

📖 Complete reference: API_REFERENCE.md

🎯 Trading Environment

💰 Initial Capital: $10,000 per AI model
📈 Trading Universe: NASDAQ 100 stocks
⏰ Trading Schedule: Weekdays only (historical simulation)
📊 Data Sources: Alpha Vantage (prices) + Jina AI (market intelligence)
🔄 Anti-Look-Ahead: Data access limited to current date and earlier

🧠 AI Agent Capabilities

Through the MCP (Model Context Protocol) toolchain, AI agents can:

📰 Research Markets - Search news, analyst reports, financial data
📊 Query Prices - Get real-time and historical OHLCV data
💰 Execute Trades - Buy/sell stocks, manage positions
🧮 Perform Calculations - Mathematical analysis and computations
📝 Log Reasoning - Document decision-making process

All operations are 100% autonomous - zero human intervention or pre-programmed strategies.

🔌 Integration Examples

Python Client

import requests
import time

class AITraderServerClient:
    def __init__(self, base_url="http://localhost:8080"):
        self.base_url = base_url

    def trigger_simulation(self, start_date, end_date=None, models=None):
        payload = {"start_date": start_date}
        if end_date:
            payload["end_date"] = end_date
        if models:
            payload["models"] = models

        response = requests.post(
            f"{self.base_url}/simulate/trigger",
            json=payload
        )
        response.raise_for_status()
        return response.json()

    def wait_for_completion(self, job_id, poll_interval=10):
        while True:
            response = requests.get(
                f"{self.base_url}/simulate/status/{job_id}"
            )
            status = response.json()

            if status["status"] in ["completed", "partial", "failed"]:
                return status

            time.sleep(poll_interval)

# Usage
client = AITraderServerClient()
job = client.trigger_simulation("2025-01-16", models=["gpt-4"])
result = client.wait_for_completion(job["job_id"])

TypeScript/JavaScript

async function runSimulation() {
  // Trigger simulation
  const response = await fetch("http://localhost:8080/simulate/trigger", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      start_date: "2025-01-16",
      models: ["gpt-4"]
    })
  });

  const job = await response.json();

  // Poll for completion
  while (true) {
    const statusResponse = await fetch(
      `http://localhost:8080/simulate/status/${job.job_id}`
    );
    const status = await statusResponse.json();

    if (["completed", "partial", "failed"].includes(status.status)) {
      return status;
    }

    await new Promise(resolve => setTimeout(resolve, 10000));
  }
}

Scheduled Automation

Use any scheduler (cron, Airflow, etc.):

#!/bin/bash
# daily_simulation.sh

DATE=$(date -d "yesterday" +%Y-%m-%d)

curl -X POST http://localhost:8080/simulate/trigger \
  -H "Content-Type: application/json" \
  -d "{\"start_date\": \"$DATE\", \"models\": [\"gpt-4\"]}"

Add to crontab:

0 6 * * * /path/to/daily_simulation.sh

📖 More examples: docs/user-guide/integration-examples.md

📖 Documentation

User Guides

Quick Start - Get running in 5 minutes
Configuration Guide - Environment setup and model configuration
Using the API - Common workflows and best practices
Integration Examples - Python, TypeScript, automation
Troubleshooting - Common issues and solutions

Developer Documentation

Development Setup - Local development without Docker
Testing Guide - Running tests and validation
Architecture - System design and components
Database Schema - SQLite table reference
Adding Models - How to add custom AI models

Deployment

Docker Deployment - Production Docker setup
Production Checklist - Pre-deployment verification
Monitoring - Health checks, logging, metrics
Scaling - Multiple instances and load balancing

Reference

API Reference - Complete endpoint documentation
Environment Variables - Configuration reference
MCP Tools - Trading tool documentation
Data Formats - File formats and schemas

🛠️ Configuration

Environment Variables

# Required API Keys
OPENAI_API_KEY=sk-your-key-here
ALPHAADVANTAGE_API_KEY=your-key-here
JINA_API_KEY=your-key-here

# Optional Configuration
API_PORT=8080                      # API server port
MAX_CONCURRENT_JOBS=1              # Max simultaneous simulations
MAX_SIMULATION_DAYS=30             # Max date range per job
AUTO_DOWNLOAD_PRICE_DATA=true     # Auto-fetch missing data

Model Configuration

Edit configs/default_config.json:

{
  "models": [
    {
      "name": "GPT-4",
      "basemodel": "openai/gpt-4",
      "signature": "gpt-4",
      "enabled": true
    },
    {
      "name": "Claude 3.7 Sonnet",
      "basemodel": "anthropic/claude-3.7-sonnet",
      "signature": "claude-3.7-sonnet",
      "enabled": true,
      "openai_base_url": "https://api.anthropic.com/v1",
      "openai_api_key": "your-anthropic-key"
    }
  ],
  "agent_config": {
    "max_steps": 30,
    "initial_cash": 10000.0
  }
}

📖 Full guide: docs/user-guide/configuration.md

🛠️ Development Mode

AI-Trader supports a development mode that mocks AI API calls for testing without costs.

Quick Start

# Set environment variables
export DEPLOYMENT_MODE=DEV
export PRESERVE_DEV_DATA=false

# Run simulation (uses mock AI, isolated dev database)
python main.py configs/default_config.json

How It Works

DEPLOYMENT_MODE=DEV:

Mock AI responses (no API calls to OpenAI/Anthropic)
Separate database: data/trading_dev.db
Separate data directory: data/dev_agent_data/
Dev database reset on startup (unless PRESERVE_DEV_DATA=true)
Warnings logged if production API keys detected

DEPLOYMENT_MODE=PROD (default):

Real AI API calls
Production database: data/trading.db
Production data directory: data/agent_data/

Mock AI Behavior

The mock provider returns deterministic responses that rotate through stocks:

Day 1: AAPL
Day 2: MSFT
Day 3: GOOGL
Etc. (cycles through 10 stocks)

Each mock response includes:

Price queries for selected stock
Buy order for 5 shares
Finish signal to end session

Environment Variables

DEPLOYMENT_MODE=PROD          # PROD or DEV (default: PROD)
PRESERVE_DEV_DATA=false      # Keep dev data between runs (default: false)

Use Cases

Orchestration testing: Verify agent loop, position tracking, logging
CI/CD pipelines: Run tests without API costs
Configuration validation: Test date ranges, model configs
Development iteration: Rapid testing of code changes

Limitations

Mock responses are static (not context-aware)
No actual market analysis
Fixed trading pattern
For logic testing only, not trading strategy validation

📊 Database Schema

SQLite database at data/jobs.db contains:

jobs - Job metadata and status
job_details - Per model-day execution details
positions - Trading position records with P&L
holdings - Portfolio holdings breakdown
reasoning_logs - AI decision reasoning history
tool_usage - MCP tool usage statistics
price_data - Historical price data cache
price_coverage - Data availability tracking

Query directly:

docker exec -it ai-trader-server sqlite3 /app/data/jobs.db
sqlite> SELECT * FROM jobs ORDER BY created_at DESC LIMIT 5;

📖 Schema reference: docs/developer/database-schema.md

🧪 Testing & Validation

Automated Validation

# Make scripts executable
chmod +x scripts/*.sh

# Validate Docker build and startup
bash scripts/validate_docker_build.sh

# Test all API endpoints
bash scripts/test_api_endpoints.sh

Unit Tests

# Install dependencies
pip install -r requirements.txt

# Run test suite
pytest tests/ -v --cov=api --cov-report=term-missing

📖 Testing guide: docs/developer/testing.md

📈 Latest Updates

v0.3.0 (Current)

Major Architecture Upgrade - REST API Service

🌐 REST API Server - Complete FastAPI implementation
- POST /simulate/trigger - Start simulation jobs with date ranges
- GET /simulate/status/{job_id} - Monitor progress in real-time
- GET /results - Query results with filtering
- GET /health - Service health checks
💾 SQLite Database - Complete persistence layer
📊 On-Demand Price Data - Automatic gap filling with priority-based downloads
🐳 Production-Ready Docker - Single-command deployment
🧪 Comprehensive Testing - 175 tests with high coverage
📚 Complete Documentation - API guides and validation procedures

See CHANGELOG.md for full release notes and ROADMAP.md for planned features.

🤝 Contributing

Contributions welcome! Please read docs/developer/CONTRIBUTING.md for development guidelines.

🙏 Acknowledgments

This project is a fork of HKUDS/AI-Trader, re-architected as a REST API service for external orchestration and integration.

📄 License

MIT License - see LICENSE for details

🔗 Links

GitHub: https://github.com/Xe138/AI-Trader-Server
Docker Hub: ghcr.io/xe138/ai-trader-server:latest
Issues: https://github.com/Xe138/AI-Trader-Server/issues
API Docs: http://localhost:8080/docs (when running)

Built with FastAPI, SQLite, Docker, and the MCP Protocol

⬆ Back to top

17 KiB Raw Permalink Blame History

🚀 AI-Trader-Server: REST API for AI Trading

🌟 What is AI-Trader-Server?

Key Features

🏗️ Architecture

🚀 Quick Start

Docker Deployment (5 minutes)

📚 API Overview

Endpoints

Example: Trigger Simulation

🎯 Trading Environment

🧠 AI Agent Capabilities

🔌 Integration Examples

Python Client

TypeScript/JavaScript

Scheduled Automation

📖 Documentation

User Guides

Developer Documentation

Deployment

Reference

🛠️ Configuration

Environment Variables

Model Configuration

🛠️ Development Mode

Quick Start

How It Works

Mock AI Behavior

Environment Variables

Use Cases

Limitations

📊 Database Schema

🧪 Testing & Validation

Automated Validation

Unit Tests

📈 Latest Updates

v0.3.0 (Current)

🤝 Contributing

🙏 Acknowledgments

📄 License

🔗 Links

17 KiB

Raw Permalink Blame History