Autoresearch Trading

A fork of karpathy/autoresearch focused on algorithmic trading.

An autonomous research system that uses an LLM agent to iteratively improve a trading strategy through backtesting with Walk-Forward Validation.

---

Assets Operated

FOREX & Gold (via MetaTrader 5)

EURUSD, GBPUSD, USDJPY, AUDUSD, USDCHF, XAUUSD

Crypto (via CCXT)

BTCUSD, ETHUSD

Primary Timeframe: M15 (15 minutes)

---

Quick Start

# 1. Install dependencies
uv sync

# 2. Configure credentials
cp .env.example .env
# Edit .env with your API keys

# 3. Prepare historical data
uv run python prepare.py

# 4. Run experimentation loop
uv run python agent.py

---

Project Structure

autoresearch-trading/
├── program.md              # Agent instructions (human edits)
├── strategy.py             # Trading strategy (agent modifies)
│
├── backtest.py             # Backtesting engine with WFV [FIXED]
├── data.py                 # OHLCV data download/caching [FIXED]
├── execute.py              # Order execution via MT5/CCXT [FIXED]
├── agent.py                # Main autoresearch loop [FIXED]
├── monitor.py              # Metrics + alerts [FIXED]
├── risk.py                 # Risk validations [FIXED]
├── config.py               # Credential loading [FIXED]
│
├── experiments.db          # SQLite: experiment log
├── best_strategy.py        # Snapshot of best Sharpe
├── results.tsv             # Tabular results
│
├── agents.md               # Agent roles and responsibilities
├── architecture.md         # Detailed system architecture
├── .env                    # Credentials (DO NOT commit)
└── pyproject.toml          # Dependencies

---

Two Agents in the System

This project operates with two types of agents:

Agent	Runs	Files it CAN Modify
External Agent (Human / Roo Code)	uv run python agent.py --interactive or direct editing	Any file: strategy.py, program.md, backtest.py, docs, etc.
Internal Agent (agent.py)	uv run python agent.py (autonomous loop)	ONLY strategy.py

⚠️ The Internal Agent is an autonomous loop that must NOT modify any file except strategy.py. All other restrictions (no modifying backtest.py, data.py, etc.) exist to keep the sharpe_wfv metric fixed and comparable.

Editable vs Fixed Files

File	Editable by Internal Agent	Purpose
strategy.py	✅ YES	Trading logic
program.md	❌ NO	Instructions for humans
backtest.py	❌ NO	Fixed comparison metric
data.py	❌ NO	Stable data interface
execute.py	❌ NO	Predictable execution
agent.py	❌ NO	Immutable main loop
monitor.py	❌ NO	Consistent alerts
risk.py	❌ NO	Non-negotiable validations

---

Metrics

Walk-Forward Validation (WFV)

The system uses sliding windows instead of a static 80/20 split:

Data:  TRAIN_1 | TEST_1 | TRAIN_2 | TEST_2 | ... | TRAIN_6 | TEST_6

sharpe_wfv = mean(sharpe_oos_windows) - 0.5 * std(sharpe_oos_windows)

Constraints

Metric	Requirement	Reason
sharpe_wfv	≥ 0	Don't lose money on average
avg_max_drawdown	< 0.15	Never exceed 15% drawdown
total_trades	≥ 200	Statistical significance

Reported Metrics

{
    "sharpe_wfv": 1.31,          # ← PRIMARY METRIC
    "sharpe_mean_oos": 1.47,
    "sharpe_std_oos": 0.32,
    "avg_max_drawdown": 0.087,
    "total_trades": 847,
    "avg_win_rate": 0.54,
    "avg_profit_factor": 1.61,
    "is_valid": true
}

---

Configuration

Environment Variables (.env)

# LLM (required)
OPENROUTER_API_KEY=sk-or-...
LLM_MODEL=minimax/minimax-m1  # Free model available

# MT5 (forex/gold)
MT5_LOGIN=123456
MT5_PASSWORD=secret
MT5_SERVER=Broker-Demo

# CCXT (crypto)
CCXT_API_KEY=your_api_key
CCXT_SECRET=your_secret

# System
MODE=paper                       # "paper" | "live"
MAX_DAILY_LOSS_PCT=0.02

# Walk-Forward Validation
WFV_N_WINDOWS=6
WFV_TRAIN_BARS=3000              # ~31 days on M15
WFV_TEST_BARS=1000               # ~10 days on M15
WFV_STEP_BARS=1000               # offset between windows

---

Dependencies

[project]
name = "autoresearch-trading"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "MetaTrader5",          # data + forex/gold execution
    "ccxt",                 # crypto execution
    "vectorbt",             # vectorized backtesting
    "pandas",
    "numpy",
    "ta-lib",               # technical indicators
    "pandas-ta",
    "openai",               # LLM client (openrouter)
    "loguru",               # structured logging
    "sqlalchemy",           # SQLite ORM
    "apscheduler",          # scheduling
    "python-dotenv",        # environment variables
    "psutil",               # resource monitoring
    "rich",                 # pretty console output
]

---

Design

Inspired by karpathy/autoresearch, the system applies the same principles to trading:

1. Single editable file — strategy.py is the only variable in the loop
2. Fixed metrics — sharpe_wfv is immutable for fair comparisons
3. Fixed time — Backtest < 30s for fast iteration (~120 experiments/hour)
4. Autonomy — The agent runs indefinitely without asking

Why Walk-Forward Validation

A static 80/20 split is fragile:

• The strategy may overfit to a specific period
• There's no way to know if it will work on future data

WFV is more robust:

• Evaluates the strategy across multiple time windows
• Variance penalty (- 0.5 * std) rewards stable strategies
• More representative of real production behavior

---

Additional Documentation

• agents.md — Agent roles and responsibilities
• architecture.md — Detailed system architecture