mirror of
https://github.com/Xe138/AI-Trader.git
synced 2026-04-01 17:17:24 -04:00
Bill
0e739a9720
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>
540 lines
17 KiB
Markdown
540 lines
17 KiB
Markdown
<div align="center">
|
|
|
|
# 🚀 AI-Trader-Server: REST API for AI Trading
|
|
|
|
[](https://python.org)
|
|
[](LICENSE)
|
|
[](https://docker.com)
|
|
[](https://fastapi.tiangolo.com)
|
|
|
|
**REST API service for autonomous AI trading competitions. Run multiple AI models in NASDAQ 100 trading simulations with zero human intervention.**
|
|
|
|
[🚀 Quick Start](QUICK_START.md) • [📚 API Reference](API_REFERENCE.md) • [📖 Documentation](#documentation)
|
|
|
|
</div>
|
|
|
|
---
|
|
|
|
## 🌟 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**
|
|
```bash
|
|
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**
|
|
```bash
|
|
docker-compose up -d
|
|
|
|
# Verify health
|
|
curl http://localhost:8080/health
|
|
```
|
|
|
|
**4. Run Simulation**
|
|
```bash
|
|
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**
|
|
```bash
|
|
# Use job_id from trigger response
|
|
curl http://localhost:8080/simulate/status/{job_id}
|
|
```
|
|
|
|
**6. View Results**
|
|
```bash
|
|
curl "http://localhost:8080/results?job_id={job_id}"
|
|
```
|
|
|
|
📖 **Detailed guide:** [QUICK_START.md](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:**
|
|
```bash
|
|
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:**
|
|
```json
|
|
{
|
|
"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](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
|
|
|
|
```python
|
|
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
|
|
|
|
```typescript
|
|
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.):
|
|
|
|
```bash
|
|
#!/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](docs/user-guide/integration-examples.md)
|
|
|
|
---
|
|
|
|
## 📖 Documentation
|
|
|
|
### User Guides
|
|
- [Quick Start](QUICK_START.md) - Get running in 5 minutes
|
|
- [Configuration Guide](docs/user-guide/configuration.md) - Environment setup and model configuration
|
|
- [Using the API](docs/user-guide/using-the-api.md) - Common workflows and best practices
|
|
- [Integration Examples](docs/user-guide/integration-examples.md) - Python, TypeScript, automation
|
|
- [Troubleshooting](docs/user-guide/troubleshooting.md) - Common issues and solutions
|
|
|
|
### Developer Documentation
|
|
- [Development Setup](docs/developer/development-setup.md) - Local development without Docker
|
|
- [Testing Guide](docs/developer/testing.md) - Running tests and validation
|
|
- [Architecture](docs/developer/architecture.md) - System design and components
|
|
- [Database Schema](docs/developer/database-schema.md) - SQLite table reference
|
|
- [Adding Models](docs/developer/adding-models.md) - How to add custom AI models
|
|
|
|
### Deployment
|
|
- [Docker Deployment](docs/deployment/docker-deployment.md) - Production Docker setup
|
|
- [Production Checklist](docs/deployment/production-checklist.md) - Pre-deployment verification
|
|
- [Monitoring](docs/deployment/monitoring.md) - Health checks, logging, metrics
|
|
- [Scaling](docs/deployment/scaling.md) - Multiple instances and load balancing
|
|
|
|
### Reference
|
|
- [API Reference](API_REFERENCE.md) - Complete endpoint documentation
|
|
- [Environment Variables](docs/reference/environment-variables.md) - Configuration reference
|
|
- [MCP Tools](docs/reference/mcp-tools.md) - Trading tool documentation
|
|
- [Data Formats](docs/reference/data-formats.md) - File formats and schemas
|
|
|
|
---
|
|
|
|
## 🛠️ Configuration
|
|
|
|
### Environment Variables
|
|
|
|
```bash
|
|
# 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`:
|
|
|
|
```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](docs/user-guide/configuration.md)
|
|
|
|
---
|
|
|
|
## 🛠️ Development Mode
|
|
|
|
AI-Trader supports a development mode that mocks AI API calls for testing without costs.
|
|
|
|
### Quick Start
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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:
|
|
```bash
|
|
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](docs/developer/database-schema.md)
|
|
|
|
---
|
|
|
|
## 🧪 Testing & Validation
|
|
|
|
### Automated Validation
|
|
|
|
```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
|
|
```
|
|
|
|
### Unit Tests
|
|
|
|
```bash
|
|
# 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](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](CHANGELOG.md) for full release notes and [ROADMAP.md](ROADMAP.md) for planned features.
|
|
|
|
---
|
|
|
|
## 🤝 Contributing
|
|
|
|
Contributions welcome! Please read [docs/developer/CONTRIBUTING.md](docs/developer/CONTRIBUTING.md) for development guidelines.
|
|
|
|
---
|
|
|
|
## 🙏 Acknowledgments
|
|
|
|
This project is a fork of [HKUDS/AI-Trader](https://github.com/HKUDS/AI-Trader), re-architected as a REST API service for external orchestration and integration.
|
|
|
|
---
|
|
|
|
## 📄 License
|
|
|
|
MIT License - see [LICENSE](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)
|
|
|
|
---
|
|
|
|
<div align="center">
|
|
|
|
**Built with FastAPI, SQLite, Docker, and the MCP Protocol**
|
|
|
|
[⬆ Back to top](#-ai-trader-server-rest-api-for-ai-trading)
|
|
|
|
</div>
|