From 20506a379dd1667848d6eac00d1904d6192814ba Mon Sep 17 00:00:00 2001
From: Bill <bill@bballou.com>
Date: Fri, 31 Oct 2025 14:57:29 -0400
Subject: [PATCH] docs: rewrite README for API-first architecture
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Complete rewrite of README.md to reflect the new REST API service
architecture and remove batch mode references.

Changes:
- Focus on REST API deployment and usage
- Updated architecture diagram showing FastAPI → Worker → Database flow
- Comprehensive API endpoint documentation with examples
- Docker-first quick start guide
- Integration examples (Windmill.dev, Python client)
- Database schema documentation
- Simplified configuration guide
- Updated project structure
- Removed batch mode references
- Removed web UI mentions

The new README positions AI-Trader as an API service for autonomous
trading simulations, not a standalone batch application.

Key additions:
- Complete API reference (/trigger, /status, /results, /health)
- Integration patterns for external orchestration
- Database querying examples
- Testing and validation procedures
- Production deployment guidance
---
 README.md | 978 ++++++++++++++++++++++++------------------------------
 1 file changed, 439 insertions(+), 539 deletions(-)

diff --git a/README.md b/README.md
index 60b2aa4..6fc0b3f 100644
--- a/README.md
+++ b/README.md
@@ -4,32 +4,12 @@
 
 [![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://python.org)
 [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
-[![Feishu](https://img.shields.io/badge/💬Feishu-Group-blue?style=flat)](./Communication.md) 
-[![WeChat](https://img.shields.io/badge/WeChat-Group-green?style=flat&logo=wechat)](./Communication.md)
+[![Docker](https://img.shields.io/badge/Docker-Ready-blue.svg)](https://docker.com)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.120+-green.svg)](https://fastapi.tiangolo.com)
 
-**Five AIs battle for NASDAQ 100 supremacy. Zero human input. Pure competition.**
+**REST API service for autonomous AI trading competitions. Run multiple AI models in NASDAQ 100 trading simulations with zero human intervention.**
 
-## 🏆 Current Championship Leaderboard 🏆 
-[*Click Here: AI Live Trading*](https://hkuds.github.io/AI-Trader/)
-
-<div align="center">
-
-###  **Championship Period: (Last Update 2025/10/29)**
-
-| 🏆 Rank | 🤖 AI Model | 📈 Total Earnings | 
-|---------|-------------|----------------|
-| **🥇 1st** | **DeepSeek** | 🚀 +16.46% |
-| 🥈 2nd | MiniMax-M2 | 📊 +12.03% |
-| 🥉 3rd | GPT-5 | 📊 +9.98% |
-| 4th | Claude-3.7 | 📊 +9.80% |
-| 5th | Qwen3-max | 📊 +7.96% |
-| Baseline | QQQ | 📊 +5.39% |
-| 6th | Gemini-2.5-flash | 📊 +0.48% |
-
-### 📊 **Live Performance Dashboard**
-![rank](assets/rank.png)
-
-*Daily Performance Tracking of AI Models in NASDAQ 100 Trading*
+[🚀 Quick Start](#-quick-start) • [📚 API Documentation](#-api-documentation) • [🐳 Docker Deployment](#-docker-deployment) • [中文文档](README_CN.md)
 
 </div>
 
@@ -39,209 +19,123 @@
 
 **Major Architecture Upgrade - REST API Service**
 
-- 🌐 **REST API Server** - Complete FastAPI implementation for external orchestration
-  - Trigger simulations via HTTP POST
-  - Monitor job progress in real-time
-  - Query results with flexible filtering
-  - Health checks and monitoring
-- 💾 **SQLite Database** - Full persistence layer with 6 relational tables
+- 🌐 **REST API Server** - Complete FastAPI implementation
+  - `POST /simulate/trigger` - Start simulation jobs
+  - `GET /simulate/status/{job_id}` - Monitor progress
+  - `GET /results` - Query results with filtering
+  - `GET /health` - Service health checks
+- 💾 **SQLite Database** - Persistent storage
   - Job tracking and lifecycle management
   - Position records with P&L tracking
   - AI reasoning logs and tool usage analytics
-- 🐳 **Docker Deployment** - Persistent REST API service
+- 🐳 **Production-Ready Docker** - Single-command deployment
   - Health checks and automatic restarts
-  - Volume persistence for database and logs
-- 🧪 **Comprehensive Testing** - 102 tests with 85% coverage
-  - Unit tests for all components
-  - Integration tests for API endpoints
-  - Validation scripts for Docker deployment
-- 📚 **Production Documentation** - Complete deployment guides
-  - DOCKER_API.md - API deployment and usage
-  - TESTING_GUIDE.md - Validation procedures
+  - Volume persistence for data and logs
+  - Simplified configuration
+- 🧪 **Comprehensive Testing** - 102 tests, 85% coverage
+- 📚 **Complete Documentation** - Deployment and validation guides
 
-See [CHANGELOG.md](CHANGELOG.md) for full details.
+See [CHANGELOG.md](CHANGELOG.md) for full release notes.
 
 ---
 
-[🚀 Quick Start](#-quick-start) • [📈 Performance Analysis](#-performance-analysis) • [🛠️ Configuration Guide](#-configuration-guide) • [中文文档](README_CN.md)
+## 🌟 What is AI-Trader?
 
-</div>
-
----
-
-## 🌟 Project Introduction
-
-> **AI-Trader enables five distinct AI models, each employing unique investment strategies, to compete autonomously in the same market and determine which can generate the highest profits in NASDAQ 100 trading!**
+> **AI-Trader enables multiple AI models to compete autonomously in NASDAQ 100 trading, making 100% independent decisions through a standardized tool-based architecture.**
 
 ### 🎯 Core Features
 
-- 🤖 **Fully Autonomous Decision-Making**: AI agents perform 100% independent analysis, decision-making, and execution without human intervention
-- 🛠️ **Pure Tool-Driven Architecture**: Built on MCP toolchain, enabling AI to complete all trading operations through standardized tool calls
-- 🏆 **Multi-Model Competition Arena**: Deploy multiple AI models (GPT, Claude, Qwen, etc.) for competitive trading
-- 📊 **Real-Time Performance Analytics**: Comprehensive trading records, position monitoring, and profit/loss analysis
-- 🔍 **Intelligent Market Intelligence**: Integrated Jina search for real-time market news and financial reports
-- ⚡ **MCP Toolchain Integration**: Modular tool ecosystem based on Model Context Protocol
-- 🔌 **Extensible Strategy Framework**: Support for third-party strategies and custom AI agent integration
-- ⏰ **Historical Replay Capability**: Time-period replay functionality with automatic future information filtering
+- 🤖 **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 Windmill.dev or any HTTP client
 
 ---
 
-### 🎮 Trading Environment
-Each AI model starts with $10,000 to trade NASDAQ 100 stocks in a controlled environment with real market data and historical replay capabilities.
-
-- 💰 **Initial Capital**: $10,000 USD starting balance
-- 📈 **Trading Universe**: NASDAQ 100 component stocks (top 100 technology stocks)
-- ⏰ **Trading Schedule**: Weekday market hours with historical simulation support
-- 📊 **Data Integration**: Alpha Vantage API combined with Jina AI market intelligence
-- 🔄 **Time Management**: Historical period replay with automated future information filtering
-
----
-
-### 🧠 Agentic Trading Capabilities
-AI agents operate with complete autonomy, conducting market research, making trading decisions, and continuously evolving their strategies without human intervention.
-
-- 📰 **Autonomous Market Research**: Intelligent retrieval and filtering of market news, analyst reports, and financial data
-- 💡 **Independent Decision Engine**: Multi-dimensional analysis driving fully autonomous buy/sell execution
-- 📝 **Comprehensive Trade Logging**: Automated documentation of trading rationale, execution details, and portfolio changes
-- 🔄 **Adaptive Strategy Evolution**: Self-optimizing algorithms that adjust based on market performance feedback
-
----
-
-### 🏁 Competition Rules
-All AI models compete under identical conditions with the same capital, data access, tools, and evaluation metrics to ensure fair comparison.
-
-- 💰 **Starting Capital**: $10,000 USD initial investment
-- 📊 **Data Access**: Uniform market data and information feeds
-- ⏰ **Operating Hours**: Synchronized trading time windows
-- 📈 **Performance Metrics**: Standardized evaluation criteria across all models
-- 🛠️ **Tool Access**: Identical MCP toolchain for all participants
-
-🎯 **Objective**: Determine which AI model achieves superior investment returns through pure autonomous operation!
-
-### 🚫 Zero Human Intervention
-AI agents operate with complete autonomy, making all trading decisions and strategy adjustments without any human programming, guidance, or intervention.
-
-- ❌ **No Pre-Programming**: Zero preset trading strategies or algorithmic rules
-- ❌ **No Human Input**: Complete reliance on inherent AI reasoning capabilities
-- ❌ **No Manual Override**: Absolute prohibition of human intervention during trading
-- ✅ **Tool-Only Execution**: All operations executed exclusively through standardized tool calls
-- ✅ **Self-Adaptive Learning**: Independent strategy refinement based on market performance feedback
-
----
-
-## ⏰ Historical Replay Architecture
-
-A core innovation of AI-Trader Bench is its **fully replayable** trading environment, ensuring scientific rigor and reproducibility in AI agent performance evaluation on historical market data.
-
-### 🔄 Temporal Control Framework
-
-#### 📅 Flexible Time Settings
-```json
-{
-  "date_range": {
-    "init_date": "2025-01-01",  // Any start date
-    "end_date": "2025-01-31"    // Any end date
-  }
-}
-```
----
-
-### 🛡️ Anti-Look-Ahead Data Controls
-AI can only access market data from current time and before. No future information allowed.
-
-- 📊 **Price Data Boundaries**: Market data access limited to simulation timestamp and historical records
-- 📰 **News Chronology Enforcement**: Real-time filtering prevents access to future-dated news and announcements
-- 📈 **Financial Report Timeline**: Information restricted to officially published data as of current simulation date
-- 🔍 **Historical Intelligence Scope**: Market analysis constrained to chronologically appropriate data availability
-
-### 🎯 Replay Advantages
-
-#### 🔬 Empirical Research Framework
-- 📊 **Market Efficiency Studies**: Evaluate AI performance across diverse market conditions and volatility regimes
-- 🧠 **Decision Consistency Analysis**: Examine temporal stability and behavioral patterns in AI trading logic
-- 📈 **Risk Management Assessment**: Validate effectiveness of AI-driven risk mitigation strategies
-
-#### 🎯 Fair Competition Framework
-- 🏆 **Equal Information Access**: All AI models operate with identical historical datasets
-- 📊 **Standardized Evaluation**: Performance metrics calculated using uniform data sources
-- 🔍 **Full Reproducibility**: Complete experimental transparency with verifiable results
-
----
-
-## 📁 Project Architecture
+## 🏗️ Architecture
 
 ```
-AI-Trader Bench/
-├── 🤖 Core System
-│   ├── main.py    # 🎯 Main program entry
-│   ├── agent/base_agent/          # 🧠 AI agent core
-│   └── configs/                   # ⚙️ Configuration files
-│
-├── 🛠️ MCP Toolchain
-│   ├── agent_tools/
-│   │   ├── tool_trade.py          # 💰 Trade execution
-│   │   ├── tool_get_price_local.py # 📊 Price queries
-│   │   ├── tool_jina_search.py   # 🔍 Information search
-│   │   └── tool_math.py           # 🧮 Mathematical calculations
-│   └── tools/                     # 🔧 Auxiliary tools
-│
-├── 📊 Data System
-│   ├── data/
-│   │   ├── daily_prices_*.json    # 📈 Stock price data
-│   │   ├── merged.jsonl           # 🔄 Unified data format
-│   │   └── agent_data/            # 📝 AI trading records
-│   └── calculate_performance.py   # 📈 Performance analysis
-│
-├── 🎨 Frontend Interface
-│   └── frontend/                  # 🌐 Web dashboard
-│
-└── 📋 Configuration & Documentation
-    ├── configs/                   # ⚙️ System configuration
-    ├── prompts/                   # 💬 AI prompts
-    └── calc_perf.sh              # 🚀 Performance calculation script
+┌─────────────────────────────────────────────────────────────┐
+│                     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                        │
+└─────────────────────────────────────────────────────────────┘
 ```
 
-### 🔧 Core Components Details
+### Key Components
 
-#### 🎯 Main Program (`main.py`)
-- **Multi-Model Concurrency**: Run multiple AI models simultaneously for trading
-- **Configuration Management**: Support for JSON configuration files and environment variables
-- **Date Management**: Flexible trading calendar and date range settings
-- **Error Handling**: Comprehensive exception handling and retry mechanisms
+- **FastAPI Server** - RESTful interface for job management and results
+- **Job Manager** - Coordinates simulation execution, prevents concurrent jobs
+- **Simulation Worker** - Orchestrates date-sequential, model-parallel execution
+- **Model-Day Executor** - Runs single model for single date with isolated config
+- **SQLite Database** - Persistent storage with 6 relational tables
+- **MCP Services** - Internal tool ecosystem (math, search, trade, price)
 
-#### 🛠️ MCP Toolchain
-| Tool | Function | API |
-|------|----------|-----|
-| **Trading Tool** | Buy/sell stocks, position management | `buy()`, `sell()` |
-| **Price Tool** | Real-time and historical price queries | `get_price_local()` |
-| **Search Tool** | Market information search | `get_information()` |
-| **Math Tool** | Financial calculations and analysis | Basic mathematical operations |
-
-#### 📊 Data System
-- **📈 Price Data**: Complete OHLCV data for NASDAQ 100 component stocks
-- **📝 Trading Records**: Detailed trading history for each AI model
-- **📊 Performance Metrics**: Sharpe ratio, maximum drawdown, annualized returns, etc.
-- **🔄 Data Synchronization**: Automated data acquisition and update mechanisms
+---
 
 ## 🚀 Quick Start
 
-### 🐳 **Docker Deployment (Recommended)**
+### 🐳 Docker Deployment (Recommended)
 
-#### 🌐 REST API Server (Windmill Integration)
+**1. Prerequisites**
+- Docker and Docker Compose installed
+- API keys: OpenAI, Alpha Vantage, Jina AI
+
+**2. Setup**
 ```bash
-# 1. Clone and configure
+# Clone repository
 git clone https://github.com/Xe138/AI-Trader.git
 cd AI-Trader
-cp .env.example .env
-# Edit .env and add your API keys
 
-# 2. Start API server
+# Configure environment
+cp .env.example .env
+# Edit .env and add your API keys:
+#   OPENAI_API_KEY=your_key_here
+#   ALPHAADVANTAGE_API_KEY=your_key_here
+#   JINA_API_KEY=your_key_here
+```
+
+**3. Start API Server**
+```bash
+# Start in background
 docker-compose up -d
 
-# 3. Test API
-curl http://localhost:8080/health
+# View logs
+docker logs -f ai-trader
 
-# 4. Trigger simulation
+# Verify health
+curl http://localhost:8080/health
+```
+
+**4. Trigger Simulation**
+```bash
 curl -X POST http://localhost:8080/simulate/trigger \
   -H "Content-Type: application/json" \
   -d '{
@@ -251,180 +145,136 @@ curl -X POST http://localhost:8080/simulate/trigger \
   }'
 ```
 
-See [DOCKER_API.md](DOCKER_API.md) for complete API documentation and [TESTING_GUIDE.md](TESTING_GUIDE.md) for validation procedures.
+**5. Monitor Progress**
+```bash
+# Get job status (use job_id from trigger response)
+curl http://localhost:8080/simulate/status/{job_id}
+
+# View results
+curl http://localhost:8080/results?job_id={job_id}
+```
 
 ---
 
-### 💻 **Local Installation (Development)**
+## 📚 API Documentation
 
-#### 📋 Prerequisites
+### Endpoints
 
-- **Python 3.10+**
-- **API Keys**: OpenAI, Alpha Vantage, Jina AI
-- **Optional**: Docker (for containerized deployment)
+#### `POST /simulate/trigger`
+Start a new simulation job.
 
-#### ⚡ Installation Steps
-
-```bash
-# 1. Clone project
-git clone https://github.com/Xe138/AI-Trader.git
-cd AI-Trader
-
-# 2. Install dependencies
-pip install -r requirements.txt
-
-# 3. Configure environment variables
-cp .env.example .env
-# Edit .env file and fill in your API keys
-```
-
-### 🔑 Environment Configuration
-
-Create `.env` file and configure the following variables:
-
-```bash
-# 🤖 AI Model API Configuration
-OPENAI_API_BASE=https://your-openai-proxy.com/v1
-OPENAI_API_KEY=your_openai_key
-
-# 📊 Data Source Configuration
-ALPHAADVANTAGE_API_KEY=your_alpha_vantage_key
-JINA_API_KEY=your_jina_api_key
-
-# 🧠 AI Agent Configuration
-AGENT_MAX_STEP=30             # Maximum reasoning steps
-```
-
-### 📦 Dependencies
-
-```bash
-# Install production dependencies
-pip install -r requirements.txt
-
-# Or manually install core dependencies
-pip install langchain langchain-openai langchain-mcp-adapters fastmcp python-dotenv requests numpy pandas
-```
-
-## 🎮 Running Guide
-
-### 📊 Step 1: Data Preparation (`./fresh_data.sh`)
-
-```bash
-# 📈 Get NASDAQ 100 stock data
-cd data
-python get_daily_price.py
-
-# 🔄 Merge data into unified format
-python merge_jsonl.py
-```
-
-### 🛠️ Step 2: Start MCP Services
-
-```bash
-cd ./agent_tools
-python start_mcp_services.py
-```
-
-### 🚀 Step 3: Start AI Arena
-
-```bash
-# 🎯 Run main program - let AIs start trading!
-python main.py
-
-# 🎯 Or use custom configuration
-python main.py configs/my_config.json
-```
-
-### ⏰ Time Settings Example
-
-#### 📅 Create Custom Time Configuration
+**Request:**
 ```json
 {
-  "agent_type": "BaseAgent",
-  "date_range": {
-    "init_date": "2024-01-01",  // Backtest start date
-    "end_date": "2024-03-31"     // Backtest end date
+  "config_path": "/app/configs/default_config.json",
+  "date_range": ["2025-01-16", "2025-01-17"],
+  "models": ["gpt-4", "claude-3.7-sonnet"]
+}
+```
+
+**Response:**
+```json
+{
+  "job_id": "550e8400-e29b-41d4-a716-446655440000",
+  "status": "pending",
+  "total_model_days": 4,
+  "message": "Simulation job created and started"
+}
+```
+
+#### `GET /simulate/status/{job_id}`
+Query job execution status and progress.
+
+**Response:**
+```json
+{
+  "job_id": "550e8400-...",
+  "status": "running",
+  "progress": {
+    "completed": 2,
+    "failed": 0,
+    "pending": 2,
+    "total": 4
   },
-  "models": [
+  "details": [
     {
-      "name": "claude-3.7-sonnet",
-      "basemodel": "anthropic/claude-3.7-sonnet",
-      "signature": "claude-3.7-sonnet",
-      "enabled": true
+      "model_signature": "gpt-4",
+      "trading_date": "2025-01-16",
+      "status": "completed",
+      "start_time": "2025-01-16T10:00:00",
+      "end_time": "2025-01-16T10:05:00"
     }
   ]
 }
 ```
 
-### 📈 Start Web Interface
+#### `GET /results`
+Retrieve simulation results with optional filtering.
 
-```bash
-cd docs
-python3 -m http.server 8000
-# Visit http://localhost:8000
+**Query Parameters:**
+- `job_id` - Filter by job UUID
+- `date` - Filter by trading date (YYYY-MM-DD)
+- `model` - Filter by model signature
+
+**Response:**
+```json
+{
+  "count": 2,
+  "results": [
+    {
+      "job_id": "550e8400-...",
+      "model_signature": "gpt-4",
+      "trading_date": "2025-01-16",
+      "final_cash": 9850.50,
+      "total_value": 10250.75,
+      "profit_loss": 250.75,
+      "positions": {...},
+      "holdings": [...]
+    }
+  ]
+}
 ```
 
-## 🐳 Docker Deployment
+#### `GET /health`
+Service health check.
 
-### Using Docker Compose (Recommended)
-
-The easiest way to run AI-Trader is with Docker Compose:
-
-```bash
-# 1. Clone and setup
-git clone https://github.com/Xe138/AI-Trader.git
-cd AI-Trader
-
-# 2. Configure environment
-cp .env.example .env
-# Edit .env with your API keys:
-# - OPENAI_API_KEY
-# - ALPHAADVANTAGE_API_KEY
-# - JINA_API_KEY
-
-# 3. Run with Docker Compose
-docker-compose up
+**Response:**
+```json
+{
+  "status": "healthy",
+  "database": "connected",
+  "timestamp": "2025-01-16T10:00:00Z"
+}
 ```
 
-The container automatically:
-- Fetches latest NASDAQ 100 price data
-- Starts all MCP services
-- Runs AI trading agents
-
-### Using Pre-built Images
-
-Pull and run pre-built images from GitHub Container Registry:
-
-```bash
-# Pull latest version
-docker pull ghcr.io/hkuds/ai-trader:latest
-
-# Run container
-docker run --env-file .env \
-  -v $(pwd)/data:/app/data \
-  -v $(pwd)/logs:/app/logs \
-  ghcr.io/hkuds/ai-trader:latest
-```
-
-**📖 See [docs/DOCKER.md](docs/DOCKER.md) for detailed Docker usage, troubleshooting, and advanced configuration.**
-
 ---
 
-## 📈 Performance Analysis
+## 🛠️ Configuration
 
-### 🏆 Competition Rules
+### Environment Variables
 
-| Rule Item | Setting | Description |
-|-----------|---------|-------------|
-| **💰 Initial Capital** | $10,000 | Starting capital for each AI model |
-| **📈 Trading Targets** | NASDAQ 100 | 100 top tech stocks |
-| **⏰ Trading Hours** | Weekdays | Monday to Friday |
-| **💲 Price Benchmark** | Opening Price | Trade using daily opening price |
-| **📝 Recording Method** | JSONL Format | Complete trading history records |
+```bash
+# AI Model API Configuration
+OPENAI_API_BASE=              # Optional: custom OpenAI proxy
+OPENAI_API_KEY=your_key_here  # Required: OpenAI API key
 
-## ⚙️ Configuration Guide
+# Data Source Configuration
+ALPHAADVANTAGE_API_KEY=your_key_here  # Required: Alpha Vantage
+JINA_API_KEY=your_key_here            # Required: Jina AI search
 
-### 📋 Configuration File Structure
+# API Server Port (host-side mapping)
+API_PORT=8080  # Change if port 8080 is occupied
+
+# Agent Configuration
+AGENT_MAX_STEP=30  # Maximum reasoning steps per day
+
+# Data Volume Configuration
+VOLUME_PATH=.  # Base directory for persistent data
+```
+
+### Configuration File
+
+Create custom configs in `configs/` directory:
 
 ```json
 {
@@ -435,16 +285,15 @@ docker run --env-file .env \
   },
   "models": [
     {
-      "name": "claude-3.7-sonnet",
-      "basemodel": "anthropic/claude-3.7-sonnet",
-      "signature": "claude-3.7-sonnet",
+      "name": "GPT-4",
+      "basemodel": "openai/gpt-4",
+      "signature": "gpt-4",
       "enabled": true
     }
   ],
   "agent_config": {
     "max_steps": 30,
     "max_retries": 3,
-    "base_delay": 1.0,
     "initial_cash": 10000.0
   },
   "log_config": {
@@ -453,236 +302,287 @@ docker run --env-file .env \
 }
 ```
 
-### 🔧 Configuration Parameters
+---
 
-| Parameter | Description | Default Value |
-|-----------|-------------|---------------|
-| `agent_type` | AI agent type | "BaseAgent" |
-| `max_steps` | Maximum reasoning steps | 30 |
-| `max_retries` | Maximum retry attempts | 3 |
-| `base_delay` | Operation delay (seconds) | 1.0 |
-| `initial_cash` | Initial capital | $10,000 |
+## 🧪 Testing & Validation
 
-### 📊 Data Format
+### Automated Validation
 
-#### 💰 Position Records (position.jsonl)
-```json
-{
-  "date": "2025-01-20",
-  "id": 1,
-  "this_action": {
-    "action": "buy",
-    "symbol": "AAPL", 
-    "amount": 10
-  },
-  "positions": {
-    "AAPL": 10,
-    "MSFT": 0,
-    "CASH": 9737.6
-  }
-}
+```bash
+# 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
 ```
 
-#### 📈 Price Data (merged.jsonl)
-```json
-{
-  "Meta Data": {
-    "2. Symbol": "AAPL",
-    "3. Last Refreshed": "2025-01-20"
-  },
-  "Time Series (Daily)": {
-    "2025-01-20": {
-      "1. buy price": "255.8850",
-      "2. high": "264.3750", 
-      "3. low": "255.6300",
-      "4. sell price": "262.2400",
-      "5. volume": "90483029"
+### Manual Testing
+
+```bash
+# 1. Start API server
+docker-compose up -d
+
+# 2. Health check
+curl http://localhost:8080/health
+
+# 3. Trigger small test job
+curl -X POST http://localhost:8080/simulate/trigger \
+  -H "Content-Type: application/json" \
+  -d '{
+    "config_path": "/app/configs/default_config.json",
+    "date_range": ["2025-01-16"],
+    "models": ["gpt-4"]
+  }'
+
+# 4. Monitor until complete
+curl http://localhost:8080/simulate/status/{job_id}
+
+# 5. View results
+curl http://localhost:8080/results?job_id={job_id}
+```
+
+See [TESTING_GUIDE.md](TESTING_GUIDE.md) for comprehensive testing procedures and troubleshooting.
+
+---
+
+## 🎯 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 (Jina AI)
+- 📊 **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.**
+
+---
+
+## 📁 Project Structure
+
+```
+AI-Trader/
+├── api/                          # FastAPI application
+│   ├── main.py                   # API server entry point
+│   ├── database.py               # SQLite schema and operations
+│   ├── job_manager.py            # Job lifecycle management
+│   ├── simulation_worker.py      # Job orchestration
+│   ├── model_day_executor.py     # Single model-day execution
+│   ├── runtime_manager.py        # Isolated runtime configs
+│   └── models.py                 # Pydantic request/response models
+│
+├── agent/                        # AI agent core
+│   └── base_agent/
+│       └── base_agent.py         # BaseAgent implementation
+│
+├── agent_tools/                  # MCP service implementations
+│   ├── tool_math.py              # Mathematical calculations
+│   ├── tool_jina_search.py       # Market intelligence search
+│   ├── tool_trade.py             # Trading execution
+│   ├── tool_get_price_local.py   # Price queries
+│   └── start_mcp_services.py     # Service orchestration
+│
+├── tests/                        # Test suite (102 tests, 85% coverage)
+│   ├── unit/                     # Unit tests
+│   └── integration/              # Integration tests
+│
+├── configs/                      # Configuration files
+│   └── default_config.json       # Default simulation config
+│
+├── scripts/                      # Validation scripts
+│   ├── validate_docker_build.sh  # Docker build validation
+│   └── test_api_endpoints.sh     # API endpoint testing
+│
+├── data/                         # Persistent data (volume mount)
+│   ├── jobs.db                   # SQLite database
+│   └── agent_data/               # Agent execution data
+│
+├── docker-compose.yml            # Docker orchestration
+├── Dockerfile                    # Container image definition
+├── entrypoint.sh                 # Container startup script
+├── requirements.txt              # Python dependencies
+└── README.md                     # This file
+```
+
+---
+
+## 🔌 Integration Examples
+
+### Windmill.dev Workflow
+
+```typescript
+// Trigger simulation
+export async function triggerSimulation(
+  api_url: string,
+  config_path: string,
+  date_range: string[],
+  models: string[]
+) {
+  const response = await fetch(`${api_url}/simulate/trigger`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ config_path, date_range, models })
+  });
+  return response.json();
+}
+
+// Poll for completion
+export async function waitForCompletion(api_url: string, job_id: string) {
+  while (true) {
+    const status = await fetch(`${api_url}/simulate/status/${job_id}`)
+      .then(r => r.json());
+
+    if (['completed', 'failed', 'partial'].includes(status.status)) {
+      return status;
     }
+
+    await new Promise(resolve => setTimeout(resolve, 10000)); // 10s poll
   }
 }
-```
 
-### 📁 File Structure
-
-```
-data/agent_data/
-├── claude-3.7-sonnet/
-│   ├── position/
-│   │   └── position.jsonl      # 📝 Position records
-│   └── log/
-│       └── 2025-01-20/
-│           └── log.jsonl       # 📊 Trading logs
-├── gpt-4o/
-│   └── ...
-└── qwen3-max/
-    └── ...
-```
-
-## 🔌 Third-Party Strategy Integration
-
-AI-Trader Bench adopts a modular design, supporting easy integration of third-party strategies and custom AI agents.
-
-### 🛠️ Integration Methods
-
-#### 1. Custom AI Agent
-```python
-# Create new AI agent class
-class CustomAgent(BaseAgent):
-    def __init__(self, model_name, **kwargs):
-        super().__init__(model_name, **kwargs)
-        # Add custom logic
-```
-
-#### 2. Register New Agent
-```python
-# Register in main.py
-AGENT_REGISTRY = {
-    "BaseAgent": {
-        "module": "agent.base_agent.base_agent",
-        "class": "BaseAgent"
-    },
-    "CustomAgent": {  # New addition
-        "module": "agent.custom.custom_agent",
-        "class": "CustomAgent"
-    },
+// Get results
+export async function getResults(api_url: string, job_id: string) {
+  return fetch(`${api_url}/results?job_id=${job_id}`)
+    .then(r => r.json());
 }
 ```
 
-#### 3. Configuration File Settings
+### Python Client
+
+```python
+import requests
+import time
+
+# Trigger simulation
+response = requests.post('http://localhost:8080/simulate/trigger', json={
+    'config_path': '/app/configs/default_config.json',
+    'date_range': ['2025-01-16', '2025-01-17'],
+    'models': ['gpt-4', 'claude-3.7-sonnet']
+})
+job_id = response.json()['job_id']
+
+# Poll for completion
+while True:
+    status = requests.get(f'http://localhost:8080/simulate/status/{job_id}').json()
+    if status['status'] in ['completed', 'failed', 'partial']:
+        break
+    time.sleep(10)
+
+# Get results
+results = requests.get(f'http://localhost:8080/results?job_id={job_id}').json()
+print(f"Completed with {results['count']} results")
+```
+
+---
+
+## 📊 Database Schema
+
+The SQLite database (`data/jobs.db`) contains:
+
+### Tables
+
+- **jobs** - Job metadata (id, status, created_at, etc.)
+- **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
+
+### Querying Data
+
+```bash
+# Direct database access
+docker exec -it ai-trader sqlite3 /app/data/jobs.db
+
+# Example queries
+sqlite> SELECT * FROM jobs ORDER BY created_at DESC LIMIT 5;
+sqlite> SELECT model_signature, AVG(profit_loss) FROM positions GROUP BY model_signature;
+sqlite> SELECT * FROM reasoning_logs WHERE job_id='...';
+```
+
+---
+
+## 🛠️ Development
+
+### Running Tests
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Run test suite
+pytest tests/ -v --cov=api --cov-report=term-missing
+
+# Run specific test
+pytest tests/unit/test_job_manager.py -v
+```
+
+### Adding Custom Models
+
+Edit `configs/default_config.json`:
+
 ```json
 {
-  "agent_type": "CustomAgent",
   "models": [
     {
-      "name": "your-custom-model",
-      "basemodel": "your/model/path",
-      "signature": "custom-signature",
-      "enabled": true
+      "name": "Custom Model",
+      "basemodel": "provider/model-name",
+      "signature": "custom-model",
+      "enabled": true,
+      "openai_base_url": "https://api.custom.com/v1",
+      "openai_api_key": "custom_key_here"
     }
   ]
 }
 ```
 
-### 🔧 Extending Toolchain
+---
 
-#### Adding Custom Tools
-```python
-# Create new MCP tool
-@mcp.tools()
-class CustomTool:
-    def __init__(self):
-        self.name = "custom_tool"
-    
-    def execute(self, params):
-        # Implement custom tool logic
-        return result
-```
+## 📖 Documentation
 
-## 🚀 Roadmap
+- [CHANGELOG.md](CHANGELOG.md) - Release notes and version history
+- [DOCKER_API.md](DOCKER_API.md) - Detailed API deployment guide
+- [TESTING_GUIDE.md](TESTING_GUIDE.md) - Comprehensive testing procedures
+- [CLAUDE.md](CLAUDE.md) - Development guide for contributors
 
-### 🌟 Future Plans
-- [ ] **🇨🇳 A-Share Support** - Extend to Chinese stock market
-- [ ] **📊 Post-Market Statistics** - Automatic profit analysis
-- [ ] **🔌 Strategy Marketplace** - Add third-party strategy sharing platform
-- [ ] **🎨 Cool Frontend Interface** - Modern web dashboard
-- [ ] **₿ Cryptocurrency** - Support digital currency trading
-- [ ] **📈 More Strategies** - Technical analysis, quantitative strategies
-- [ ] **⏰ Advanced Replay** - Support minute-level time precision and real-time replay
-- [ ] **🔍 Smart Filtering** - More precise future information detection and filtering
+---
 
-## 🤝 Contributing Guide
+## 🤝 Contributing
 
-We welcome contributions of all kinds! Especially AI trading strategies and agent implementations.
+Contributions welcome! Please read [CLAUDE.md](CLAUDE.md) for development guidelines.
 
-### 🧠 AI Strategy Contributions
-- **🎯 Trading Strategies**: Contribute your AI trading strategy implementations
-- **🤖 Custom Agents**: Implement new AI agent types
-- **📊 Analysis Tools**: Add new market analysis tools
-- **🔍 Data Sources**: Integrate new data sources and APIs
-
-### 🐛 Issue Reporting
-- Use GitHub Issues to report bugs
-- Provide detailed reproduction steps
-- Include system environment information
-
-### 💡 Feature Suggestions
-- Propose new feature ideas in Issues
-- Describe use cases in detail
-- Discuss implementation approaches
-
-### 🔧 Code Contributions
-1. Fork the project
-2. Create a feature branch
-3. Implement your strategy or feature
-4. Add test cases
-5. Create a Pull Request
-
-### 📚 Documentation Improvements
-- Improve README documentation
-- Add code comments
-- Write usage tutorials
-- Contribute strategy documentation
-
-### 🏆 Strategy Sharing
-- **📈 Technical Analysis Strategies**: AI strategies based on technical indicators
-- **📊 Quantitative Strategies**: Multi-factor models and quantitative analysis
-- **🔍 Fundamental Strategies**: Analysis strategies based on financial data
-- **🌐 Macro Strategies**: Strategies based on macroeconomic data
-
-## 📞 Support & Community
-
-- **💬 Discussions**: [GitHub Discussions](https://github.com/Xe138/AI-Trader/discussions)
-- **🐛 Issues**: [GitHub Issues](https://github.com/Xe138/AI-Trader/issues)
+---
 
 ## 📄 License
 
-This project is licensed under the [MIT License](LICENSE).
+MIT License - see [LICENSE](LICENSE) for details
 
-## 🙏 Acknowledgments
+---
 
-Thanks to the following open source projects and services:
-- [LangChain](https://github.com/langchain-ai/langchain) - AI application development framework
-- [MCP](https://github.com/modelcontextprotocol) - Model Context Protocol
-- [Alpha Vantage](https://www.alphavantage.co/) - Financial data API
-- [Jina AI](https://jina.ai/) - Information search service
+## 🔗 Links
 
-## Disclaimer
-
-The materials provided by the AI-Trader project are for research purposes only and do not constitute any investment advice. Investors should seek independent professional advice before making any investment decisions. Past performance, if any, should not be taken as an indicator of future results. You should note that the value of investments may go up as well as down, and there is no guarantee of returns. All content of the AI-Trader project is provided solely for research purposes and does not constitute a recommendation to invest in any of the mentioned securities or sectors. Investing involves risks. Please seek professional advice if needed.
+- **GitHub**: https://github.com/Xe138/AI-Trader
+- **Docker Hub**: `ghcr.io/xe138/ai-trader:latest`
+- **Issues**: https://github.com/Xe138/AI-Trader/issues
 
 ---
 
 <div align="center">
 
-**🌟 If this project helps you, please give us a Star!**
-
-[![GitHub stars](https://img.shields.io/github/stars/Xe138/AI-Trader?style=social)](https://github.com/Xe138/AI-Trader)
-[![GitHub forks](https://img.shields.io/github/forks/Xe138/AI-Trader?style=social)](https://github.com/Xe138/AI-Trader)
-
-**🤖 Experience AI's full potential in financial markets through complete autonomous decision-making!**  
-**🛠️ Pure tool-driven execution with zero human intervention—a genuine AI trading arena!** 🚀
+**Built with FastAPI, SQLite, Docker, and the MCP Protocol**
 
 </div>
-
----
-
-## ⭐ Star History
-
-*Community Growth Trajectory*
-
-<div align="center">
-  <a href="https://star-history.com/#HKUDS/AI-Trader&Date">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=HKUDS/AI-Trader&type=Date&theme=dark" />
-      <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=HKUDS/AI-Trader&type=Date" />
-      <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=HKUDS/AI-Trader&type=Date" style="border-radius: 15px; box-shadow: 0 0 30px rgba(0, 217, 255, 0.3);" />
-    </picture>
-  </a>
-</div>
-
----
-
-<p align="center">
-  <em> ❤️ Thanks for visiting ✨ AI-Trader!</em><br><br>
-  <img src="https://visitor-badge.laobi.icu/badge?page_id=HKUDS.AI-Trader&style=for-the-badge&color=00d4ff" alt="Views">
-</p>