mirror of
https://github.com/Xe138/AI-Trader.git
synced 2026-04-01 17:17:24 -04:00
Add CLAUDE.md for repository guidance
Provides comprehensive guidance for working with the AI-Trader codebase including: - Development commands for setup, data preparation, and running simulations - Architecture overview of agent system, MCP toolchain, and data flow - Configuration system with multi-layered priority - Data formats for positions and price data - Implementation details and common troubleshooting steps
This commit is contained in:
284
CLAUDE.md
Normal file
284
CLAUDE.md
Normal file
@@ -0,0 +1,284 @@
|
|||||||
|
# CLAUDE.md
|
||||||
|
|
||||||
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||||
|
|
||||||
|
## Project Overview
|
||||||
|
|
||||||
|
AI-Trader is an autonomous AI trading competition platform where multiple AI models compete in NASDAQ 100 trading with zero human intervention. Each AI starts with $10,000 and uses standardized MCP (Model Context Protocol) tools to make fully autonomous trading decisions.
|
||||||
|
|
||||||
|
**Key Innovation:** Historical replay architecture with anti-look-ahead controls ensures AI agents can only access data from the current simulation date and earlier.
|
||||||
|
|
||||||
|
## Development Commands
|
||||||
|
|
||||||
|
### Environment Setup
|
||||||
|
```bash
|
||||||
|
# Install dependencies
|
||||||
|
pip install -r requirements.txt
|
||||||
|
|
||||||
|
# Configure environment variables
|
||||||
|
cp .env.example .env
|
||||||
|
# Edit .env and set:
|
||||||
|
# - OPENAI_API_BASE, OPENAI_API_KEY
|
||||||
|
# - ALPHAADVANTAGE_API_KEY, JINA_API_KEY
|
||||||
|
# - RUNTIME_ENV_PATH (recommended: absolute path to runtime_env.json)
|
||||||
|
# - MCP service ports (default: 8000-8003)
|
||||||
|
# - AGENT_MAX_STEP (default: 30)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Data Preparation
|
||||||
|
```bash
|
||||||
|
# Download/update NASDAQ 100 stock data
|
||||||
|
cd data
|
||||||
|
python get_daily_price.py # Fetch daily prices from Alpha Vantage
|
||||||
|
python merge_jsonl.py # Merge into unified format (merged.jsonl)
|
||||||
|
cd ..
|
||||||
|
```
|
||||||
|
|
||||||
|
### Starting Services
|
||||||
|
```bash
|
||||||
|
# Start all MCP services (Math, Search, Trade, LocalPrices)
|
||||||
|
cd agent_tools
|
||||||
|
python start_mcp_services.py
|
||||||
|
cd ..
|
||||||
|
|
||||||
|
# Services run on ports defined in .env:
|
||||||
|
# - MATH_HTTP_PORT (default: 8000)
|
||||||
|
# - SEARCH_HTTP_PORT (default: 8001)
|
||||||
|
# - TRADE_HTTP_PORT (default: 8002)
|
||||||
|
# - GETPRICE_HTTP_PORT (default: 8003)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Running Trading Simulations
|
||||||
|
```bash
|
||||||
|
# Run with default config
|
||||||
|
python main.py
|
||||||
|
|
||||||
|
# Run with custom config
|
||||||
|
python main.py configs/my_config.json
|
||||||
|
|
||||||
|
# Environment variables can override config dates:
|
||||||
|
INIT_DATE=2025-01-01 END_DATE=2025-01-31 python main.py
|
||||||
|
```
|
||||||
|
|
||||||
|
### Complete Workflow
|
||||||
|
```bash
|
||||||
|
# All-in-one startup script (data + services + trading + web)
|
||||||
|
bash main.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
### Core Components
|
||||||
|
|
||||||
|
**1. Agent System** (`agent/base_agent/base_agent.py`)
|
||||||
|
- `BaseAgent`: Base class for all trading agents
|
||||||
|
- Manages MCP tool connections, AI model initialization, trading execution loops
|
||||||
|
- Handles position management and logging
|
||||||
|
- Supports retry logic with exponential backoff (`max_retries`, `base_delay`)
|
||||||
|
|
||||||
|
**2. Main Entry Point** (`main.py`)
|
||||||
|
- Dynamic agent class loading via `AGENT_REGISTRY`
|
||||||
|
- Multi-model concurrent trading support
|
||||||
|
- Date range validation and weekday filtering
|
||||||
|
- Configuration management (JSON + environment variables)
|
||||||
|
|
||||||
|
**3. MCP Toolchain** (`agent_tools/`)
|
||||||
|
- `tool_math.py`: Mathematical calculations (port 8000)
|
||||||
|
- `tool_jina_search.py`: Market intelligence search (port 8001)
|
||||||
|
- `tool_trade.py`: Buy/sell execution (port 8002)
|
||||||
|
- `tool_get_price_local.py`: Price queries (port 8003)
|
||||||
|
- `start_mcp_services.py`: Service orchestration with health checks
|
||||||
|
|
||||||
|
**4. Data Management** (`data/`)
|
||||||
|
- `daily_prices_*.json`: Individual stock OHLCV data
|
||||||
|
- `merged.jsonl`: Unified price data format
|
||||||
|
- `agent_data/[signature]/position/position.jsonl`: Position records
|
||||||
|
- `agent_data/[signature]/log/[date]/log.jsonl`: Trading logs
|
||||||
|
|
||||||
|
**5. Utilities** (`tools/`)
|
||||||
|
- `general_tools.py`: Config management, message extraction
|
||||||
|
- `price_tools.py`: Price queries, position updates
|
||||||
|
- `result_tools.py`: Performance calculations
|
||||||
|
|
||||||
|
### Data Flow
|
||||||
|
|
||||||
|
1. **Initialization**: Agent loads config, connects to MCP services, initializes AI model
|
||||||
|
2. **Trading Loop**: For each date:
|
||||||
|
- Get system prompt with current positions, yesterday's prices, today's buy prices
|
||||||
|
- AI agent analyzes market, calls search/math/price tools
|
||||||
|
- Makes buy/sell decisions via trade tool
|
||||||
|
- Logs all decisions and updates position.jsonl
|
||||||
|
3. **Position Tracking**: Each trade appends to `position.jsonl` with date, action, and updated holdings
|
||||||
|
|
||||||
|
### Configuration System
|
||||||
|
|
||||||
|
**Multi-layered config priority:**
|
||||||
|
1. Environment variables (highest)
|
||||||
|
2. Model-specific config (`openai_base_url`, `openai_api_key` in model config)
|
||||||
|
3. JSON config file
|
||||||
|
4. Default values (lowest)
|
||||||
|
|
||||||
|
**Runtime configuration** (`runtime_env.json` at `RUNTIME_ENV_PATH`):
|
||||||
|
- Dynamic state: `TODAY_DATE`, `SIGNATURE`, `IF_TRADE`
|
||||||
|
- Written by `write_config_value()`, read by `get_config_value()`
|
||||||
|
|
||||||
|
### Agent System
|
||||||
|
|
||||||
|
**BaseAgent Key Methods:**
|
||||||
|
- `initialize()`: Connect to MCP services, create AI model
|
||||||
|
- `run_trading_session(date)`: Execute single day's trading with retry logic
|
||||||
|
- `run_date_range(init_date, end_date)`: Process all weekdays in range
|
||||||
|
- `get_trading_dates()`: Resume from last date in position.jsonl
|
||||||
|
- `register_agent()`: Create initial position file with $10,000 cash
|
||||||
|
|
||||||
|
**Adding Custom Agents:**
|
||||||
|
1. Create new class inheriting from `BaseAgent`
|
||||||
|
2. Add to `AGENT_REGISTRY` in `main.py`:
|
||||||
|
```python
|
||||||
|
"CustomAgent": {
|
||||||
|
"module": "agent.custom.custom_agent",
|
||||||
|
"class": "CustomAgent"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
3. Set `"agent_type": "CustomAgent"` in config JSON
|
||||||
|
|
||||||
|
### System Prompt Construction
|
||||||
|
|
||||||
|
**Dynamic prompt generation** (`prompts/agent_prompt.py`):
|
||||||
|
- `get_agent_system_prompt()` builds prompt with:
|
||||||
|
- Current date
|
||||||
|
- Yesterday's closing positions
|
||||||
|
- Yesterday's closing prices
|
||||||
|
- Today's buy prices
|
||||||
|
- Yesterday's profit/loss
|
||||||
|
- AI agent must output `<FINISH_SIGNAL>` to end trading session
|
||||||
|
|
||||||
|
### Anti-Look-Ahead Controls
|
||||||
|
|
||||||
|
**Data access restrictions:**
|
||||||
|
- Price data: Only returns data for `date <= TODAY_DATE`
|
||||||
|
- Search results: News filtered by publication date
|
||||||
|
- All tools enforce temporal boundaries via `TODAY_DATE` from `runtime_env.json`
|
||||||
|
|
||||||
|
## Configuration File Format
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"agent_type": "BaseAgent",
|
||||||
|
"date_range": {
|
||||||
|
"init_date": "2025-01-01",
|
||||||
|
"end_date": "2025-01-31"
|
||||||
|
},
|
||||||
|
"models": [
|
||||||
|
{
|
||||||
|
"name": "model-display-name",
|
||||||
|
"basemodel": "provider/model-id",
|
||||||
|
"signature": "unique-identifier",
|
||||||
|
"enabled": true,
|
||||||
|
"openai_base_url": "optional-override",
|
||||||
|
"openai_api_key": "optional-override"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"agent_config": {
|
||||||
|
"max_steps": 30, // Max reasoning iterations per day
|
||||||
|
"max_retries": 3, // Retry attempts on failure
|
||||||
|
"base_delay": 1.0, // Base retry delay (seconds)
|
||||||
|
"initial_cash": 10000.0
|
||||||
|
},
|
||||||
|
"log_config": {
|
||||||
|
"log_path": "./data/agent_data"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Data Formats
|
||||||
|
|
||||||
|
**Position Record** (`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
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**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"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Important Implementation Details
|
||||||
|
|
||||||
|
**Trading Day Logic:**
|
||||||
|
- Only weekdays (Monday-Friday) are processed
|
||||||
|
- `get_trading_dates()` automatically resumes from last date in `position.jsonl`
|
||||||
|
- Skips days already processed (idempotent)
|
||||||
|
|
||||||
|
**Error Handling:**
|
||||||
|
- All async operations use `_ainvoke_with_retry()` with exponential backoff
|
||||||
|
- MCP service failures raise detailed error messages with troubleshooting hints
|
||||||
|
- Missing API keys halt startup with clear error messages
|
||||||
|
|
||||||
|
**Tool Message Extraction:**
|
||||||
|
- `extract_conversation(response, "final")`: Get AI's final answer
|
||||||
|
- `extract_tool_messages(response)`: Get all tool results
|
||||||
|
- Handles both dict and object-based message formats
|
||||||
|
|
||||||
|
**Logging:**
|
||||||
|
- Each trading day creates `log/[date]/log.jsonl`
|
||||||
|
- Logs include timestamps, signature, and all message exchanges
|
||||||
|
- Position updates append to single `position/position.jsonl`
|
||||||
|
|
||||||
|
## Testing Changes
|
||||||
|
|
||||||
|
When modifying agent behavior or adding tools:
|
||||||
|
1. Create test config with short date range (2-3 days)
|
||||||
|
2. Set `max_steps` low (e.g., 10) to iterate faster
|
||||||
|
3. Check logs in `data/agent_data/[signature]/log/[date]/`
|
||||||
|
4. Verify position updates in `position/position.jsonl`
|
||||||
|
5. Use `main.sh` only for full end-to-end testing
|
||||||
|
|
||||||
|
## Common Issues
|
||||||
|
|
||||||
|
**MCP Services Not Running:**
|
||||||
|
- Error: "Failed to initialize MCP client"
|
||||||
|
- Fix: `cd agent_tools && python start_mcp_services.py`
|
||||||
|
- Verify ports not already in use: `lsof -i :8000-8003`
|
||||||
|
|
||||||
|
**Missing Price Data:**
|
||||||
|
- Ensure `data/merged.jsonl` exists
|
||||||
|
- Run `cd data && python get_daily_price.py && python merge_jsonl.py`
|
||||||
|
- Check Alpha Vantage API key is valid
|
||||||
|
|
||||||
|
**Runtime Config Issues:**
|
||||||
|
- Set `RUNTIME_ENV_PATH` to absolute path in `.env`
|
||||||
|
- Ensure directory is writable
|
||||||
|
- File gets created automatically on first run
|
||||||
|
|
||||||
|
**Agent Doesn't Stop Trading:**
|
||||||
|
- Agent must output `<FINISH_SIGNAL>` within `max_steps`
|
||||||
|
- Increase `max_steps` if agent needs more reasoning time
|
||||||
|
- Check `log.jsonl` for errors preventing completion
|
||||||
Reference in New Issue
Block a user