AI-Trader/docs/user-guide/configuration.md

Configuration Guide

Complete guide to configuring AI-Trader-Server.

---

Environment Variables

Set in .env file in project root.

Required Variables

# OpenAI API (or compatible endpoint)
OPENAI_API_KEY=sk-your-key-here

# Alpha Vantage (price data)
ALPHAADVANTAGE_API_KEY=your-key-here

# Jina AI (market intelligence search)
JINA_API_KEY=your-key-here

Optional Variables

# API Server Configuration
API_PORT=8080                       # Host port mapping (default: 8080)
API_HOST=0.0.0.0                   # Bind address (default: 0.0.0.0)

# OpenAI Configuration
OPENAI_API_BASE=https://api.openai.com/v1  # Custom endpoint

# Simulation Limits
MAX_CONCURRENT_JOBS=1               # Max simultaneous jobs (default: 1)
MAX_SIMULATION_DAYS=30              # Max date range per job (default: 30)

# Price Data Management
AUTO_DOWNLOAD_PRICE_DATA=true       # Auto-fetch missing data (default: true)

# Agent Configuration
AGENT_MAX_STEP=30                   # Max reasoning steps per day (default: 30)

# Volume Paths
VOLUME_PATH=.                       # Base directory for data (default: .)

# MCP Service Ports (usually don't need to change)
MATH_HTTP_PORT=8000
SEARCH_HTTP_PORT=8001
TRADE_HTTP_PORT=8002
GETPRICE_HTTP_PORT=8003

---

Model Configuration

Edit configs/default_config.json to define available AI models.

Configuration Structure

{
  "agent_type": "BaseAgent",
  "date_range": {
    "init_date": "2025-01-01",
    "end_date": "2025-01-31"
  },
  "models": [
    {
      "name": "GPT-4",
      "basemodel": "openai/gpt-4",
      "signature": "gpt-4",
      "enabled": true
    }
  ],
  "agent_config": {
    "max_steps": 30,
    "max_retries": 3,
    "initial_cash": 10000.0
  },
  "log_config": {
    "log_path": "./data/agent_data"
  }
}

Model Configuration Fields

Field	Required	Description
name	Yes	Display name for the model
basemodel	Yes	Model identifier (e.g., openai/gpt-4, anthropic/claude-3.7-sonnet)
signature	Yes	Unique identifier used in API requests and database
enabled	Yes	Whether this model runs when no models specified in API request
openai_base_url	No	Custom API endpoint for this model
openai_api_key	No	Model-specific API key (overrides OPENAI_API_KEY env var)

Adding Custom Models

Example: Add Claude 3.7 Sonnet

{
  "models": [
    {
      "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"
    }
  ]
}

Example: Add DeepSeek via OpenRouter

{
  "models": [
    {
      "name": "DeepSeek",
      "basemodel": "deepseek/deepseek-chat",
      "signature": "deepseek",
      "enabled": true,
      "openai_base_url": "https://openrouter.ai/api/v1",
      "openai_api_key": "your-openrouter-key"
    }
  ]
}

Agent Configuration

Field	Description	Default
max_steps	Maximum reasoning iterations per trading day	30
max_retries	Retry attempts on API failures	3
initial_cash	Starting capital per model	10000.0

---

Port Configuration

Default Ports

Service	Internal Port	Host Port (configurable)
API Server	8080	API_PORT (default: 8080)
MCP Math	8000	Not exposed to host
MCP Search	8001	Not exposed to host
MCP Trade	8002	Not exposed to host
MCP Price	8003	Not exposed to host

Changing API Port

If port 8080 is already in use:

# Add to .env
echo "API_PORT=8889" >> .env

# Restart
docker-compose down
docker-compose up -d

# Access on new port
curl http://localhost:8889/health

---

Volume Configuration

Docker volumes persist data across container restarts:

volumes:
  - ./data:/app/data          # Database, price data, agent data
  - ./configs:/app/configs    # Configuration files
  - ./logs:/app/logs          # Application logs

Data Directory Structure

data/
├── jobs.db                      # SQLite database
├── merged.jsonl                 # Cached price data
├── daily_prices_*.json          # Individual stock data
├── price_coverage.json          # Data availability tracking
└── agent_data/                  # Agent execution data
    └── {signature}/
        ├── position/
        │   └── position.jsonl   # Trading positions
        └── log/
            └── {date}/
                └── log.jsonl    # Trading logs

---

API Key Setup

OpenAI API Key

1. Visit platform.openai.com/api-keys
2. Create new key
3. Add to .env:

   OPENAI_API_KEY=sk-...
   

Alpha Vantage API Key

1. Visit alphavantage.co/support/#api-key
2. Get free key (5 req/min) or premium (75 req/min)
3. Add to .env:

   ALPHAADVANTAGE_API_KEY=...
   

Jina AI API Key

1. Visit jina.ai
2. Sign up for free tier
3. Add to .env:

   JINA_API_KEY=...
   

---

Configuration Examples

Development Setup

# .env
API_PORT=8080
MAX_CONCURRENT_JOBS=1
MAX_SIMULATION_DAYS=5           # Limit for faster testing
AUTO_DOWNLOAD_PRICE_DATA=true
AGENT_MAX_STEP=10               # Fewer steps for faster iteration

Production Setup

# .env
API_PORT=8080
MAX_CONCURRENT_JOBS=1
MAX_SIMULATION_DAYS=30
AUTO_DOWNLOAD_PRICE_DATA=true
AGENT_MAX_STEP=30

Multi-Model Competition

// configs/default_config.json
{
  "models": [
    {
      "name": "GPT-4",
      "basemodel": "openai/gpt-4",
      "signature": "gpt-4",
      "enabled": true
    },
    {
      "name": "Claude 3.7",
      "basemodel": "anthropic/claude-3.7-sonnet",
      "signature": "claude-3.7",
      "enabled": true,
      "openai_base_url": "https://api.anthropic.com/v1",
      "openai_api_key": "anthropic-key"
    },
    {
      "name": "GPT-3.5 Turbo",
      "basemodel": "openai/gpt-3.5-turbo",
      "signature": "gpt-3.5-turbo",
      "enabled": false  // Not run by default
    }
  ]
}

---

Environment Variable Priority

When the same configuration exists in multiple places:

1. API request parameters (highest priority)
2. Model-specific config (openai_base_url, openai_api_key in model config)
3. Environment variables (.env file)
4. Default values (lowest priority)

Example:

// If model config has:
{
  "openai_api_key": "model-specific-key"
}

// This overrides OPENAI_API_KEY from .env

---

Validation

After configuration changes:

# Restart service
docker-compose down
docker-compose up -d

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

# Check logs for errors
docker logs ai-trader-server | grep -i error