An implementation of Cognitive Alpha Mining via LLM-Driven Code-Based Evolution (arXiv 2511.18850v3).
CogAlpha is a framework that uses large language models to automatically discover alpha factors for quantitative trading. It combines a seven-level agent hierarchy, multi-agent quality control, and thinking-driven evolution to iteratively generate and refine alpha factors expressed as Python code.
┌──────────────────────────────┐
│ 24-Gen Evolution Loop │
│ (3 sub-cycles × 8 gens each) │
└──────────────┬───────────────┘
┌──────────────────────────┼──────────────────────────┐
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌─────────────────┐
│ Agent Generation│ │ Evolution │ │ Backtest Engine │
│ L1 ─→ L7 │ │ Mutation │ │ LightGBM │
│ layer rotation │ │ Crossover │ │ Top-50/drop-5 │
│ CoT-aware │ │ CoT extract │ │ IR · AER │
└───────┬───────┘ └───────┬───────┘ └────────┬────────┘
│ │ │
└────────────┬───────────┘ │
▼ │
┌─────────────────┐ │
│ Quality Checker │ │
│ QuickCheck │ │
│ Execution │ │
│ 4 LLM Agents │ │
└────────┬───────┘ │
│ │
▼ │
┌─────────────────┐ │
│ Evaluation │◄────────────────────────────┘
│ IC · RankIC │
│ ICIR · RankICIR │
│ MI · classify │
└─────────────────┘
# Clone
git clone <repo-url>
cd Alpha-Agent
# Install dependencies
pip install -r requirements.txt
# Set up LLM API key
cp .env.example .env
# Edit .env with your API key and model# Backtest engine
python tests/test_backtest.py
# Evolution + CoT + parent selection
python tests/test_evo_basics.py
# Quality checker non-LLM pipeline
python tests/test_quality_checker.py
# Full comparison framework (Tier 1)
python tests/test_final_comparison.py# One generation of evolution (mutation + crossover)
python tests/test_one_generation.py
# 3-generation pipeline (2 LLM injection points)
python tests/test_pipeline_e2e.py
# Short LLM comparison (3 gens)
python tests/test_final_comparison.py --llm-short
# Full 24-generation paper-scale experiment (~50 min)
python tests/test_final_comparison.py --llm-full# Fetch CSI300 data (requires akshare, needs network)
python -c "from src.data.fetcher import fetch_csi300_real; train,val,test = fetch_csi300_real(n_stocks=50)"
# Run backtest with alpha factors
python -c "
from src.data.fetcher import generate_mock_data
from src.evaluation.backtest import run_full_backtest
df = generate_mock_data(n_stocks=50, n_days=300)
result = run_full_backtest(factor_codes, df_train=df, df_test=df)
print(f'IR={result[\"metrics\"][\"ir\"]:.4f}, AER={result[\"metrics\"][\"aer\"]:.4f}')
"Alpha-Agent/
├── src/
│ ├── config.py # Global configuration
│ ├── data/
│ │ └── fetcher.py # CSI300 data + mock data + target
│ ├── executor/
│ │ └── sandbox.py # Secure alpha code execution
│ ├── evaluation/
│ │ ├── metrics.py # IC, RankIC, ICIR, RankICIR, MI
│ │ ├── pipeline.py # 24-gen evolution orchestrator
│ │ └── backtest.py # LightGBM + portfolio sim + IR/AER
│ └── agents/
│ ├── llm_client.py # LLM API client (OpenAI-compatible)
│ ├── prompts.py # 27 agent + 4 QC + 2 evo prompts
│ ├── layers_l1_l4.py # 13 agents (L1–L4)
│ ├── layers_l5_l7.py # 8 agents (L5–L7)
│ ├── quality_checker.py # QuickCheck + 4 LLM QC agents
│ └── thinking_evolution.py # Mutation + Crossover + CoT
├── tests/
│ ├── test_backtest.py # Backtest unit tests
│ ├── test_evo_basics.py # CoT + parent selection
│ ├── test_quality_checker.py # QC non-LLM tests
│ ├── test_one_generation.py # 1-gen LLM evolution test
│ ├── test_pipeline_e2e.py # 3-gen pipeline integration test
│ └── test_final_comparison.py # Comparison framework (3 tiers)
├── docs/ # Session-by-session documentation
├── paper_full.txt # Extracted paper text
├── 2511.18850v3.pdf # Original paper (arXiv)
├── .env.example # API key template
├── requirements.txt
└── README.md
- 3 sub-cycles × 8 generations = 24 total
- Agent injection every 2 gens: fresh alphas from task-specific agents enter the pool
- Evolution every gen: parent pool → 3× children via mutation/crossover/both
- Layer rotation: injected agents cycle through L1→L7 (
gen_id % 7 + 1) - Top-2 elite carry: best elites survive to next gen's parent selection
- CoT feedback: effective/ineffective patterns injected into next gen's prompts
- QuickCheck: AST-level, catches nested loops, naming issues
- Execution Check: NaN/Inf overflow, numerical stability
- 4 LLM Agents: CodeQuality → Judge → Repair → Improve (full QC mode)
- 5 metrics per factor: IC, RankIC, ICIR, RankICIR, MI
- Classification: percentile-based + absolute thresholds
- QUALIFIED: ≥65th percentile + IC≥0.005, RankIC≥0.005, ICIR≥0.05, RankICIR≥0.05, MI≥0.02
- ELITE: ≥80th percentile + IC≥0.01, RankIC≥0.01, ICIR≥0.1, RankICIR≥0.1, MI≥0.02
- LightGBM rolling training (step=126), paper-spec hyperparameters
- Portfolio: top-50 by prediction, max 5 daily turnover
- Cost model: open 0.05%, close 0.15%, min 5 CNY
- Metrics: IR = μ/σ × √252, AER = μ × 252
- Target: 10-day open-to-open return (buy at open[t+1], sell at open[t+11])
| Paper Element | Section | Status |
|---|---|---|
| 7-level agent hierarchy (27 agents) | §3.2 | ✓ |
| Diversified guidance (5 strategies) | §3.3 | ✓ |
| Multi-agent quality checker | §3.4 | ✓ |
| Adaptive generation + CoT extraction | §3.5 | ✓ |
| Thinking evolution (mutation + crossover) | §3.6 | ✓ |
| 24-gen cycle (3×8 sub-cycles) | B.4 | ✓ |
| Agent injection every 2 gens | B.4 | ✓ |
| Top-2 elite carry-forward | §3.4 | ✓ |
| 5 predictive power metrics | §3.4, B.3 | ✓ |
| 10-day open-to-open target | §4.1 | ✓ |
| LightGBM rolling training (step=126) | §4.1, B.4 | ✓ |
| Top-50/drop-5 portfolio + costs | B.2 | ✓ |
| IR / AER computation | B.3 | ✓ |
| CSI300 real data pipeline | §4.1, B.1 | ready |
| Cross-dataset (S&P500, HSI, etc.) | §4.1, B.11 | not yet |
See src/config.py and .env.example:
# .env
OPENAI_API_KEY=sk-xxx # Your LLM API key
OPENAI_BASE_URL=https://api.deepseek.com
OPENAI_MODEL=deepseek-v4-flashKey configurable parameters in config.py:
| Parameter | Default | Description |
|---|---|---|
PARENT_POOL_SIZE |
32 | Parents per evolution generation |
CHILDREN_POOL_MULTIPLIER |
3 | Children = 3 × parents = 96 |
EVAL_QUALIFIED_PERCENTILE |
65 | Qualified percentile threshold |
EVAL_ELITE_PERCENTILE |
80 | Elite percentile threshold |
N_TOTAL_GENERATIONS |
24 | Total generations |
N_SUB_CYCLES |
3 | Sub-cycles per agent |
AGENT_INJECT_EVERY |
2 | Inject fresh agents every N gens |
LGB_NUM_LEAVES |
32 | LightGBM leaves per tree |
BACKTEST_TOP_K |
50 | Portfolio size |
BACKTEST_MAX_TURNOVER |
5 | Max daily position changes |
Progressive documentation covering each phase of implementation:
| Session | Topic | File |
|---|---|---|
| 1 | Paper overview + project scaffold | docs/session1-overview.md |
| 2 | Evaluation metrics + classification | docs/session2-metrics.md |
| 3 | Agent hierarchy (L1-L4, 13 agents) | docs/session3-agents.md |
| 4 | Agent hierarchy (L5-L7, 8 agents) | docs/session4-l5-l7.md |
| 5 | Multi-agent quality checker | docs/session5-quality-checker.md |
| 6 | Thinking evolution (mutation + crossover) | docs/session6-thinking-evolution.md |
| 7 | Pipeline integration | docs/session7-pipeline-integration.md |
| 8-10 | Data, backtest, 24-gen paper cycle | docs/session8-10-final-stage.md |
This project is an educational implementation of the CogAlpha paper (arXiv 2511.18850v3).