gavindiaz/NexQuant
1
0
Fork 0
mirror of https://github.com/NicolasBohn/NexQuant.git synced 2026-07-27 15:37:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: rewrite README — Numba loop, Optuna, ML, zero-LLM strategy discovery

Browse Source
This commit is contained in:
TPTBusiness
2026-05-31 17:25:43 +02:00
parent 6cd362aa25
commit 7d7c267d29
1 changed files with 127 additions and 537 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+127 -537
View File
@@ -3,26 +3,25 @@
<p align="center">
<img src="https://img.shields.io/badge/Python-3.10%20|%203.11-blue?style=for-the-badge&logo=python" alt="Python">
<img src="https://img.shields.io/badge/Platform-Linux-lightgrey?style=for-the-badge&logo=linux" alt="Platform">
<img src="https://img.shields.io/badge/PyTorch-2.0+-red?style=for-the-badge&logo=pytorch" alt="PyTorch">
<img src="https://img.shields.io/badge/Optuna-3.5+-009B77?style=for-the-badge&logo=optuna" alt="Optuna">
<img src="https://img.shields.io/badge/Numba-0.59+-00A3E0?style=for-the-badge&logo=numba" alt="Numba">
<img src="https://img.shields.io/badge/Optuna-4.8+-009B77?style=for-the-badge&logo=optuna" alt="Optuna">
</p>
<p align="center">
<img src="https://img.shields.io/badge/Pandas-150458?style=for-the-badge&logo=pandas" alt="Pandas">
<img src="https://img.shields.io/badge/LightGBM-00A1E0?style=for-the-badge" alt="LightGBM">
<img src="https://img.shields.io/badge/Qlib-FF6B6B?style=for-the-badge" alt="Qlib">
<img src="https://img.shields.io/badge/llama.cpp-7B68EE?style=for-the-badge" alt="llama.cpp">
<img src="https://img.shields.io/badge/TA--Lib-0.6+-green?style=for-the-badge" alt="TA-Lib">
<img src="https://img.shields.io/badge/LightGBM-4.6+-00A1E0?style=for-the-badge" alt="LightGBM">
<img src="https://img.shields.io/badge/Pandas-2.0+-150458?style=for-the-badge&logo=pandas" alt="Pandas">
<img src="https://img.shields.io/badge/cTrader-OpenAPI-FF6B6B?style=for-the-badge" alt="cTrader">
</p>
<h4 align="center">
<strong>AI-powered Quantitative Research Framework</strong>
<strong>High-Speed Strategy Discovery Framework</strong>
</h4>
<p align="center">
<a href="#installation">Installation</a> •
<a href="#no-gpu-use-openrouter">No GPU?</a> •
<a href="#quick-start">Quick Start</a> •
<a href="#configuration">Configuration</a> •
<a href="#strategy-discovery">Strategy Discovery</a> •
<a href="#live-trading">Live Trading</a> •
<a href="#features">Features</a>
</p>
@@ -33,27 +32,12 @@
<a href="https://github.com/TPTBusiness/NexQuant/actions/workflows/codacy.yml">
<img src="https://img.shields.io/github/actions/workflow/status/TPTBusiness/NexQuant/codacy.yml?branch=master&label=Security&logo=shield&style=flat-square" alt="Security Scan">
</a>
<a href="https://codecov.io/gh/TPTBusiness/NexQuant">
<img src="https://img.shields.io/codecov/c/github/TPTBusiness/NexQuant?style=flat-square&logo=codecov" alt="Coverage">
</a>
<a href="https://github.com/TPTBusiness/NexQuant/blob/master/LICENSE">
<img src="https://img.shields.io/github/license/TPTBusiness/NexQuant?style=flat-square" alt="License">
</a>
<a href="https://www.conventionalcommits.org/">
<img src="https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow?style=flat-square" alt="Conventional Commits">
</a>
<a href="https://github.com/astral-sh/ruff">
<img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json&style=flat-square" alt="Ruff">
</a>
<a href="https://github.com/TPTBusiness/NexQuant/stargazers">
<img src="https://img.shields.io/github/stars/TPTBusiness/NexQuant?style=flat-square" alt="Stars">
</a>
<a href="https://github.com/TPTBusiness/NexQuant/forks">
<img src="https://img.shields.io/github/forks/TPTBusiness/NexQuant?style=flat-square" alt="Forks">
</a>
<a href="https://github.com/TPTBusiness/NexQuant/issues">
<img src="https://img.shields.io/github/issues/TPTBusiness/NexQuant?style=flat-square" alt="Issues">
</a>
<a href="https://github.com/TPTBusiness/NexQuant/commits/master">
<img src="https://img.shields.io/github/last-commit/TPTBusiness/NexQuant?style=flat-square" alt="Last Commit">
</a>
@@ -61,434 +45,116 @@
---
## 🖥️ CLI Dashboard
```bash
rdagent nexquant
```
![NexQuant CLI Welcome Screen](docs/cli-welcome-screen.png)
*The NexQuant CLI shows system status, available commands, and quick start guide.*
---
## Overview
**NexQuant** is an autonomous AI agent for quantitative strategy research. Built on a multi-agent framework, it automates the full R&D cycle:
**NexQuant** discovers profitable trading strategies through high-speed search — no LLM required. Core engine: Numba JIT-compiled backtest at **735 million bars/second** (245× faster than pandas). Four discovery methods run in a continuous loop:
- 📊 **Factor Generation** — LLM proposes novel alpha factors; CoSTEER evolves code through iterative improvement
- 🔍 **Strategy Discovery** — R&D loop generates and evaluates hundreds of strategies across multiple timeframes
- 🧠 **Model Evolution** — Thompson-sampling bandit balances factor vs. model generation for optimal discovery
- 📈 **Price-Action R&D Loop** — Deterministic technical indicator optimization (no LLM required)
- ⚡ **Backtesting Engine** — Unified engine with runtime invariants, walk-forward validation
| Method | Frequency | Description |
|--------|-----------|-------------|
| **Explore** | 30% of iterations | Random strategies from 17 TA-Lib indicators across timeframes |
| **Exploit** | 70% of iterations | Mutate the best-known strategy (change params, indicator, or timeframe) |
| **Optuna** | Every 500 iterations | 20-trial hyperparameter optimization on the current best |
| **LightGBM** | Every 2000 iterations | ML classifier trained on SOTA indicator signals to predict direction |
> **This repository contains the research framework.** Trading strategies, broker integrations, and live trading infrastructure are available as separate closed-source modules.
**Current best strategy**: MACD(3,10,3) 4-TF with 2/4 vote majority — **+32.0%/month** (Numba), **+24.3%/month** (verified independent backtest), 0/75 negative months.
NexQuant works with any OHLCV data in HDF5 MultiIndex format. It supports local LLMs (llama.cpp) and cloud backends (OpenRouter).
> **Backtest Verification**: Every result is verified against mathematical invariants (MaxDD ∈ [-1,0], WinRate ∈ [0,1], Sharpe finite, sign consistency). 1125+ collected tests with property-based, fuzzing, and hypothesis tests.
## Acknowledgments
This project draws inspiration from various open-source projects in the AI trading and multi-agent systems space. We thank all the authors for their innovative work that helped shape our understanding of these patterns.
Special thanks to:
- **[Microsoft RD-Agent](https://github.com/microsoft/RD-Agent)** (MIT License) - Foundation for our autonomous R&D agent framework. We extend our gratitude to the RD-Agent team for their excellent foundational work.
- **[TradingAgents](https://github.com/TauricResearch/TradingAgents)** (Apache 2.0 License) - Inspiration for our multi-agent debate system, reflection mechanism, and memory management modules.
- **[ai-hedge-fund](https://github.com/virattt/ai-hedge-fund)** - Inspiration for macro analysis (Stanley Druckenmiller agent), risk management concepts, and market regime detection.
All code in NexQuant is originally written and implemented independently.
---
## Installation
### System Requirements
| Component | Minimum | Recommended |
|-----------|---------|-------------|
| **GPU VRAM** | 8 GB | 16 GB (RTX 4080 / 5060 Ti) |
| **RAM** | 16 GB | 32 GB |
| **Storage** | 20 GB | 50 GB (models + data) |
| **OS** | Linux (Ubuntu 22.04+) | Linux |
| **CUDA** | 12.0+ | 12.4+ |
> Local LLMs require a CUDA-capable GPU. The default model (Qwen3.6-35B Q3) uses ~13.6 GB VRAM. CPU-only inference is possible but very slow (not recommended for production use).
### Prerequisites
- **Conda** (Miniconda or Anaconda) — required for environment management
- **Docker** — required for sandboxed factor/model code execution (`docker run hello-world` to verify)
- **llama.cpp** — for local LLM inference (see [llama.cpp build guide](https://github.com/ggml-org/llama.cpp))
- **Ollama** — for embeddings (`nomic-embed-text`); install from [ollama.com](https://ollama.com) and run `ollama pull nomic-embed-text`
- **Linux** — officially supported; macOS/Windows may work with adjustments
### Quick Install
```bash
# Clone repository
git clone https://github.com/TPTBusiness/NexQuant
cd NexQuant
# Create and activate conda environment
conda create -n nexquant python=3.10 -y
conda activate nexquant
# Install in editable mode
pip install -e .
# Verify Docker is accessible
docker run --rm hello-world
```
> **Important:** NexQuant requires a conda environment to manage dependencies properly.
> Using plain Python or other environment managers may cause conflicts.
---
## Data Setup
NexQuant requires **OHLCV data** in HDF5 MultiIndex format. The framework is instrument-agnostic — any symbol with OHLCV bars can be used.
### Step 1: Get the data
Download OHLCV data from any of these free sources:
| Source | Cost | Notes |
|--------|------|-------|
| **[Dukascopy](https://www.dukascopy.com/swiss/english/marketfeed/historical/)** | Free | High-quality tick data |
| **[OANDA API](https://developer.oanda.com/)** | Free (demo) | Requires API key, programmatic access |
| **[TrueFX](https://truefx.com/)** | Free | Institutional-quality tick data |
| **[Kaggle](https://www.kaggle.com/datasets?search=EURUSD+1min)** | Free | Search "OHLCV 1 minute" |
| **MetaTrader 5** | Free | Export via `copy_rates_range()` |
### Step 2: Convert to HDF5
```python
import pandas as pd
df = pd.read_csv('ohlcv_data.csv', parse_dates=['datetime'])
df = df.rename(columns={'open': '$open', 'close': '$close',
'high': '$high', 'low': '$low', 'volume': '$volume'})
df['instrument'] = 'SYMBOL'
df = df.set_index(['datetime', 'instrument'])
for col in ['$open', '$close', '$high', '$low', '$volume']:
df[col] = df[col].astype('float32')
import os
os.makedirs('git_ignore_folder/factor_implementation_source_data', exist_ok=True)
df.to_hdf('git_ignore_folder/factor_implementation_source_data/intraday_pv.h5', key='data', mode='w')
```
### Required HDF5 format
| Field | Type | Description |
|-------|------|-------------|
| **Index** | MultiIndex `(datetime, instrument)` | Timestamp + currency pair |
| **`$open`** | float32 | Open price |
| **`$close`** | float32 | Close price |
| **`$high`** | float32 | High price |
| **`$low`** | float32 | Low price |
| **`$volume`** | float32 | Tick volume |
**Save location:** `git_ignore_folder/factor_implementation_source_data/intraday_pv.h5`
---
## Configuration
### Environment Setup
Create a `.env` file in the project root:
```bash
# Local LLM (llama.cpp)
OPENAI_API_KEY=local
OPENAI_API_BASE=http://localhost:8081/v1
CHAT_MODEL=qwen3.5-35b
# Embedding (Ollama)
LITELLM_PROXY_API_KEY=local
LITELLM_PROXY_API_BASE=http://localhost:11434/v1
EMBEDDING_MODEL=nomic-embed-text
# Paths
QLIB_DATA_DIR=~/.qlib/qlib_data/market_data
```
### LLM Server (llama.cpp)
```bash
~/llama.cpp/build/bin/llama-server \
--model ~/models/qwen3.6/Qwen3.6-35B-A3B-UD-Q3_K_XL.gguf \
--n-gpu-layers 18 \
--no-mmap \
--port 8081 \
--ctx-size 260000 \
--parallel 2 \
--batch-size 512 --ubatch-size 512 \
--host 0.0.0.0 \
-ctk q4_0 -ctv q4_0 \
--reasoning off
```
> **Important flags:**
> - `--ctx-size 260000 --parallel 2` — allocates **2 slots × 130,000 tokens each**.
> - `--reasoning off` — **critical**: completely disables Qwen3 chain-of-thought. `--reasoning-budget 0` is not sufficient and produces empty JSON responses.
> - `--n-gpu-layers 18` — reduced from max (33) to free ~7 GB VRAM for Kronos-small GPU inference alongside llama-server.
> - `-ctk q4_0 -ctv q4_0` — quantises the KV cache to 4-bit, reducing VRAM usage.
### Data Configuration
Edit [`data_config.yaml`](data_config.yaml) to customize walk-forward splits:
```yaml
instrument: SYMBOL
frequency: 1min
data_path: ~/.qlib/qlib_data/market_data
train_start: "2022-03-14"
train_end: "2024-06-30"
valid_start: "2024-07-01"
valid_end: "2024-12-31"
test_start: "2025-01-01"
test_end: "2026-03-20"
market_context:
spread_bps: 1.5
target_arr: 9.62
max_drawdown: 20
```
---
## No GPU? Use OpenRouter
If you don't have a CUDA-capable GPU, you can run NexQuant using [OpenRouter](https://openrouter.ai) for LLM inference — no local model download required.
**1. Set up `.env` for OpenRouter:**
```bash
# Chat (OpenRouter)
OPENAI_API_KEY=sk-or-v1-<your-openrouter-key>
OPENAI_API_BASE=https://openrouter.ai/api/v1
CHAT_MODEL=qwen/qwen3-235b-a22b
# Embedding (Ollama — still required locally)
LITELLM_PROXY_API_KEY=local
LITELLM_PROXY_API_BASE=http://localhost:11434/v1
EMBEDDING_MODEL=nomic-embed-text
```
**2. Skip the llama-server step** — no local LLM server needed.
**3. Run with the OpenRouter backend:**
```bash
rdagent fin_quant --model openrouter
```
**4. Parallel runs** (uses API concurrency instead of GPU slots):
```bash
python scripts/nexquant_parallel.py --runs 5 --api-keys 1 -m openrouter
```
> Ollama is still required for embeddings even in the OpenRouter path. Install from [ollama.com](https://ollama.com) and run `ollama pull nomic-embed-text` once.
> **This repository contains the research framework.** Trading strategies, broker integrations, and live trading infrastructure are available as separate closed-source modules (`git_ignore_folder/`).
---
## Quick Start
### Prerequisites checklist
```bash
# 1. Docker running?
docker run --rm hello-world
# Prerequisites
conda create -n nexquant python=3.10 -y && conda activate nexquant
pip install -e .
# Ensure OHLCV data exists: git_ignore_folder/intraday_pv_all.h5
# 2. Data in place?
ls git_ignore_folder/factor_implementation_source_data/intraday_pv.h5
# Strategy Discovery Loop (10,000 iterations, ~1 hour)
python scripts/nexquant_rd_loop.py --iterations 10000
# 3. LLM server running?
curl http://localhost:8081/health
```
# Price-Action Indicator Loop (grid search all TA-Lib indicators)
python scripts/nexquant_priceaction_loop.py
### 1. Run Trading Loop
```bash
conda activate nexquant
rdagent fin_quant
# or with explicit options:
rdagent fin_quant --loop-n 5 --step-n 2
```
### 2. Monitor Results
```bash
# Web dashboard
rdagent server_ui --port 19899 --log-dir git_ignore_folder/RD-Agent_workspace/
# then open http://127.0.0.1:19899
# Best strategies so far
python nexquant.py best
```
### 3. Run Continuously (Auto-Restart)
```bash
# Start all services with auto-restart daemons:
# fin_quant — factor R&D loop
nohup bash -c 'while true; do rdagent fin_quant --loop-n 10 --model local >> /tmp/fin_quant_daemon.log 2>&1; sleep 10; done' &
# Autopilot — 24/7 strategy generator
nohup python scripts/nexquant_autopilot.py >> /tmp/autopilot_daemon.log 2>&1 &
# Top strategies report
python nexquant.py best -n 20 -m monthly_return --min-trades 30
```
---
## CLI Commands
## Strategy Discovery
### Factor & Strategy Loop
### R&D Loop (`scripts/nexquant_rd_loop.py`)
| Command | Description |
|---------|-------------|
| `rdagent fin_quant` | Start autonomous factor + model evolution loop |
| `rdagent fin_quant --loop-n 5` | Run exactly 5 evolution loops |
| `rdagent fin_quant --with-dashboard` | Start with web dashboard |
| `rdagent fin_quant --cli-dashboard` | Start with CLI Rich dashboard |
| `rdagent fin_factor` | Factor-only evolution |
| `rdagent fin_model` | Model-only evolution |
```
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ Explore │ ──→ │ Exploit │ ──→ │ Optuna │ ──→ │ LightGBM │
│ (Random) │ │ (Mutate) │ │ (Tuning) │ │ (ML) │
└──────────┘ └──────────┘ └──────────┘ └──────────┘
30% 70% /500 iter /2000 iter
```
### Strategy Reports
**17 TA-Lib indicators**: MACD, RSI, Donchian, SAR, ADX, BBANDS, CCI, WCLPRICE, MFI, OBV, STOCH, ROC, AROON, AROONOSC, MOM, ULTOSC, WILLR
| Command | Description |
|---------|-------------|
| `python nexquant.py best` | Show top strategies by composite score |
| `python nexquant.py best -n 20 -m sharpe` | Top 20 by Sharpe ratio |
| `python nexquant.py best --show NAME` | Full metadata for one strategy |
| `python scripts/nexquant_gen_strategies_real_bt.py 10` | Generate 10 strategies with LLM + real OHLCV backtest |
| `python scripts/nexquant_gen_strategies_real_bt.py 20` | Generate 20 strategies (parallel workers) |
| `python scripts/nexquant_autopilot.py` | 24/7 Auto-Pilot: endless strategy generation |
| `python scripts/nexquant_continuous_strategies.py` | Continuous generation with ML training
**4 timeframes**: 15min, 30min, 1h, 4h
### Kronos Foundation Model
**3 strategy types**: Single-TF, Multi-TF (vote majority), Portfolio (indicator ensemble)
| Command | Description |
|---------|-------------|
| `rdagent fin_quant` | Kronos factors auto-generated on startup (3 horizons) |
| Model size: `KRONOS_MODEL_SIZE=small\|mini\|base` | Configurable via env (default: small) |
**Discovery example** (50,000 iterations):
```
random → SAR(+65) → MACD(+73) → MACD-mutated(+102.75, +32%/month)
↓
Optuna tuned params
↓
LightGBM ensemble
```
Kronos runs automatically — no separate command needed. Factors are regenerated if missing from `results/factors/`.
### Grid Search (`scripts/nexquant_priceaction_loop.py`)
### Factor Evaluation
Deterministic parameter grid over all 17 indicators. Finds MACD(3,10,3) as optimal.
| Command | Description |
|---------|-------------|
| `python nexquant.py evaluate --all` | Evaluate all generated factors |
| `python nexquant.py top -n 20` | Show top 20 factors by IC |
| `python nexquant.py portfolio-simple` | Simple portfolio optimization |
### Portfolio Optimizer (`scripts/nexquant_portfolio_optimizer.py`)
### Parallel Execution
Greedy correlation-aware selection from discovered strategies.
| Command | Description |
|---------|-------------|
| `python scripts/nexquant_parallel.py --runs 5 --api-keys 1 -m openrouter` | Run 5 parallel factor evolutions |
| `python scripts/nexquant_parallel.py --runs 20 --api-keys 2 -m openrouter` | Run 20 runs with 2 API keys |
---
### Monitoring & Debug
## Live Trading
| Command | Description |
|---------|-------------|
| `rdagent server_ui --port 19899 --log-dir <path>` | Start web dashboard |
| `rdagent health_check` | Validate environment setup |
| `python scripts/nexquant_batch_backtest.py` | Batch backtest multiple factors |
| `python scripts/nexquant_rebacktest_strategies.py` | Re-backtest existing strategies |
Closed-source module at `git_ignore_folder/nexquant_live_trader.py`. Architecture:
```
MACD(3,10,3) Signal → cTrader OpenAPI → Live Account
4-TF 2/4 Votes (WebSocket+Protobuf) ↓
Paper Mode
```
Integration: cTrader WebSocket `live.ctraderapi.com:5035`, OAuth2 authentication, Protobuf message encoding, FIX protocol.
---
## Features
### 🔄 Iterative Factor Evolution
### ⚡ Numba Backtest
- 735M bars/second (0.003s for 2.26M bars)
- JIT-compiled profit/drawdown/sharpe computation
- Signal construction via pandas resample + TA-Lib (~0.4s) is the bottleneck
NexQuant continuously proposes, implements, and validates new alpha factors:
### 🔍 Four Discovery Methods
- **Explore**: Random indicator + timeframe + parameters
- **Exploit**: Mutation of top-5 SOTA strategies (parameter tweak, indicator swap, timeframe change)
- **Optuna**: 20-trial TPE hyperparameter optimization on best strategy
- **LightGBM**: ML classifier on SOTA indicator signals (80/20 train/test split)
- Learns from backtest feedback
- Avoids overfitting through walk-forward validation
- Discovers non-obvious patterns in order flow, volatility, and session dynamics
### 🛡️ Trading Protection System
Automatic risk management to prevent excessive losses:
- **Max Drawdown Protection** - Pauses trading when drawdown exceeds threshold (default: 15%)
- **Cooldown Period** - Enforces mandatory rest period after significant losses (default: 4h after 5% loss)
- **Stoploss Guard** - Detects clusters of stoplosses and blocks trading (default: max 5 per day)
- **Low Performance Filter** - Filters out consistently underperforming factors (Sharpe < 0.5, Win Rate < 40%)
### 🧠 Model Architecture Search
Automatically explores and refines predictive models:
- Linear baselines (LightGBM, XGBoost)
- Deep learning (LSTM, Transformer, Temporal CNN)
- Ensemble methods
### 📚 Knowledge Base
Built-in knowledge accumulation across loops:
- Successful factors are archived
- Failed attempts inform future proposals
- Cross-loop learning improves robustness
### 🖥️ Interactive UI
Real-time dashboard for monitoring:
- Factor performance metrics
- Model architecture evolution
- Cumulative returns and drawdowns
- Code diffs and implementation history
### 🤖 Kronos Foundation Model Integration
NexQuant integrates Kronos — an OHLCV foundation model from the NeoQuasar team (AAAI 2026, **MIT License**) — for alpha factor generation:
| Model | Params | p24 IC | Best For |
|-------|--------|--------|----------|
| **Kronos-small** (default) | 25M | \|IC\| ≈ 0.09 | OHLCV data |
| Kronos-mini | 4.1M | \|IC\| ≈ 0.07 | Low-resource |
| Kronos-base | 102M | \|IC\| ≈ 0.002 | Daily/weekly data only |
Kronos generates 3 prediction-horizon factors automatically on `fin_quant` startup:
- `KronosPredReturn_p24` — 24-minute horizon
- `KronosPredReturn_p48` — 48-minute horizon
- `KronosPredReturn_p96` — 96-minute horizon (best performer)
The model runs on GPU (CUDA) alongside the llama-server, using CPU as fallback.
Factors are persisted in `results/factors/` for use by the strategy orchestrator.
```bash
# Kronos runs automatically with fin_quant (no separate command needed)
rdagent fin_quant --loop-n 10 --model local
# Model size is auto-detected and configurable via env
# Set KRONOS_MODEL_SIZE=base to use the 102M-param model
```
### 📊 TA-Lib Integration
- 17 indicators with full parameter ranges
- Auto-guard against bad parameters (negative/zero values that crash TA-Lib)
- Multi-timeframe voting with configurable threshold
### 🔒 Security & Quality
Automated quality assurance:
- **1,125+ collected tests** — deep property-based, fuzzing, and hypothesis tests on every commit
- **Bandit Security Scanner** — pre-commit security checks
- **Weekly Dependency Audit** — automated vulnerability scan via GitHub Actions
- **Closed-source detection** — CI verifies no local/ files are accidentally committed
- 0 Dependabot alerts, 0 CodeScan alerts
- No proprietary terms in git history
- Closed-source detection CI
---
@@ -496,143 +162,67 @@ Automated quality assurance:
```
nexquant/
├── rdagent/ # Core agent framework
│ ├── app/ # CLI and scenario apps
│ │ └── qlib_rd_loop/ # Quant R&D loop (factor + model generation)
│ ├── components/ # Reusable agent components
│ │ ├── backtesting/ # Backtest engine & protections
│ │ │ ├── vbt_backtest.py # Unified backtest engine (OHLCV bars)
│ │ │ ├── verify.py # Runtime backtest invariant checker
│ │ │ ├── results_db.py
│ │ │ └── protections/ # Trading protection system
│ │ ├── coder/ # Factor & model coding
│ │ │ ├── CoSTEER/ # LLM-based code evolution engine
│ │ │ ├── factor_coder/ # Factor-specific coders
│ │ │ ├── model_coder/ # Model-specific coders
│ │ │ └── kronos_adapter.py # Kronos foundation model adapter
│ │ └── workflow/ # R&D loop workflow
│ ├── core/ # Core abstractions
│ ├── oai/ # LLM backend (LiteLLM, streaming, retry)
│ ├── log/ # Logging infrastructure
│ ├── scenarios/ # Domain-specific scenarios (qlib, kaggle, rl)
│ └── utils/ # Utilities
├── scripts/ # Daily operation scripts
│ ├── nexquant_autopilot.py # 24/7 auto strategy generator
│ ├── nexquant_gen_strategies_real_bt.py # Parallel strategy generation
│ ├── nexquant_parallel.py # Multi-instance parallel R&D
│ ├── nexquant_continuous_strategies.py # Continuous strategy generation
│ ├── nexquant_fast_rebacktest.py # Fast strategy re-evaluation
│ └── nexquant_rebacktest_parent.py # Parallel rebacktest orchestrator
├── test/ # Test suite (1,125+ collected)
│ ├── backtesting/ # Backtest engine deep tests
│ ├── qlib/ # Quant loop, factor, model tests
│ ├── oai/ # LLM backend tests
│ ├── log/ # Logger tests
│ ├── local/ # Closed-source tests (autopilot, ML, strategies)
│ └── integration/ # End-to-end pipeline tests
├── data_config.yaml # Walk-forward split configuration
├── pyproject.toml # Project metadata
├── requirements.txt # Dependencies
└── AGENTS.md # Agent configuration & workflow guide
├── scripts/ # Strategy discovery & trading
│ ├── nexquant_rd_loop.py # High-speed R&D loop (Numba + Optuna + ML)
│ ├── nexquant_priceaction_loop.py # TA-Lib grid search loop
│ ├── nexquant_portfolio_optimizer.py # Correlation-aware portfolio selection
│ ├── nexquant_gridsearch.py # Deterministic parameter grid search
│ ├── nexquant_daily_strategies.py # Daily Kronos + factor combinations
│ ├── nexquant_gen_strategies_real_bt.py # LLM-based strategy generation
│ ├── nexquant_autopilot.py # 24/7 continuous generator
│ └── nexquant_parallel.py # Multi-instance parallel runs
├── rdagent/ # Core framework (LLM-based, see note below)
│ ├── app/ # CLI and scenario apps
│ ├── components/ # Backtest engine, protections, coders
│ ├── core/ # Core abstractions
│ ├── scenarios/ # Domain-specific scenarios
│ └── utils/ # Utilities
├── git_ignore_folder/ # Closed-source (never committed)
│ ├── nexquant_live_trader.py # cTrader live trading
│ ├── nexquant_fix_trader.py # FIX protocol trader
│ ├── intraday_pv_all.h5 # OHLCV data
│ ├── gbpusdt_1min.h5 # GBP/USD data
│ └── btc_1min.h5 # BTC data
├── test/ # 1,125+ collected tests
├── data_config.yaml # Walk-forward split configuration
├── requirements.txt # Dependencies
└── AGENTS.md # Agent configuration & workflow guide
```
> **Note on `rdagent/`**: The LLM-based R&D framework (`rdagent fin_quant`) is part of the codebase but the Qlib/CoSTEER pipeline currently produces zero factors. The primary strategy discovery path is the Numba-based loop in `scripts/`.
---
## Requirements
## Installation
Core dependencies (see [`requirements.txt`](requirements.txt) for full list):
### Prerequisites
- **Conda** (Miniconda or Anaconda)
- **TA-Lib** system library (`apt install ta-lib` or `brew install ta-lib`)
- **Linux** (Ubuntu 22.04+)
- **LLM**: `openai`, `litellm`
- **Data**: `pandas`, `numpy`, `pyarrow`
- **ML**: `scikit-learn`, `lightgbm`, `xgboost`
- **Backtesting**: `qlib` (via Docker)
- **UI**: `streamlit`, `plotly`, `flask`
### Install
```bash
git clone https://github.com/TPTBusiness/NexQuant && cd NexQuant
conda create -n nexquant python=3.10 -y && conda activate nexquant
pip install -e .
```
### Data
Place OHLCV HDF5 data at `git_ignore_folder/intraday_pv_all.h5`:
```python
# Format: MultiIndex (datetime, instrument), columns: $open $close $high $low $volume
df.to_hdf('git_ignore_folder/intraday_pv_all.h5', key='data')
```
---
## License
This project is licensed under the **GNU Affero General Public License v3.0 (AGPL-3.0)**.
Key points of AGPL-3.0:
- You may use, modify, and distribute this software freely
- If you distribute modified versions, you MUST publish your changes under the same AGPL-3.0 license
- If you run this software as a network service (e.g., trading API), you MUST make the complete source code available to users
- Includes patent protection and anti-tivoization clauses
See the full license text in [`LICENSE`](LICENSE) or at <https://www.gnu.org/licenses/agpl-3.0.en.html>.
---
## Contributing
Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch (`git checkout -b feat/my-feature`)
3. Commit using [Conventional Commits](https://www.conventionalcommits.org/) (`git commit -m 'feat: add my feature'`)
4. Push to the branch (`git push origin feat/my-feature`)
5. Open a Pull Request with a conventional commit title
For major changes, please open an issue first to discuss your approach.
---
## Citation
If you use NexQuant in your research, please cite the underlying framework:
```bibtex
@misc{yang2025rdagentllmagentframeworkautonomous,
title={R&D-Agent: An LLM-Agent Framework Towards Autonomous Data Science},
author={Yang, Xu and Yang, Xiao and Fang, Shikai and Zhang, Yifei and Wang, Jian and Xian, Bowen and Li, Qizheng and Li, Jingyuan and Xu, Minrui and Li, Yuante and others},
year={2025},
eprint={2505.14738},
archivePrefix={arXiv},
primaryClass={cs.AI}
}
```
---
## Support
- **Issues**: [GitHub Issues](https://github.com/TPTBusiness/NexQuant/issues)
---
## Backtest Integrity
Every backtest result is automatically verified at runtime against 10 mathematical invariants.
The verifier runs in **<1ms** and catches corrupted/missing/flipped metrics before they enter the factor database.
### Runtime checks (every backtest)
| Check | Constraint |
|-------|-----------|
| Max Drawdown | `-1.0 ≤ mdd ≤ 0.0` |
| Win Rate | `0.0 ≤ wr ≤ 1.0` |
| Sharpe Ratio | `sharpe` must be finite |
| Total Return | `total_return` must be finite |
| Trade Count | `n_trades ≥ 0` |
| Sign consistency | `sign(sharpe) == sign(annual_return)` |
| Status | Must be `success` or `failed` |
### Test suite (CI + pre-commit)
```bash
pytest test/ -q # 1,125+ collected, property-based + fuzzing
pytest test/backtesting/ -q # backtest engine deep tests
```
**Coverage**: IC linear invariance, forward-return alignment, cross-implementation validation, ground-truth hand-computed scenarios, look-ahead bias detection, edge cases (all-NaN, constant, zero-variance, 1-bar, empty series), Monte Carlo p-value, walk-forward rolling, buy-and-hold equality, property-based testing (hypothesis: cost monotonicity, signal inversion, max-DD invariants), fuzzing (1,000 random backtest results), autopilot failure recovery, threshold rescaling, API key distribution, ML model acceptance criteria.
**GNU Affero General Public License v3.0 (AGPL-3.0)**. See [`LICENSE`](LICENSE).
---
## Disclaimer
NexQuant is provided "as is" for **research and educational purposes only**. It is **not** intended for:
- Live trading or financial advice
- Production use without thorough testing
- Replacement of qualified financial professionals
Users assume all liability and should comply with applicable laws and regulations in their jurisdiction. Past performance does not guarantee future results.
NexQuant is provided for **research and educational purposes only**. Past performance does not guarantee future results. Users assume all liability.