diff --git a/README.md b/README.md index 0bd3405c..93f69bea 100644 --- a/README.md +++ b/README.md @@ -3,26 +3,25 @@

Python Platform - PyTorch - Optuna + Numba + Optuna

- Pandas - LightGBM - Qlib - llama.cpp + TA-Lib + LightGBM + Pandas + cTrader

- AI-powered Quantitative Research Framework + High-Speed Strategy Discovery Framework

- Installation • - No GPU? • Quick Start • - Configuration • + Strategy Discovery • + Live Trading • Features

@@ -33,27 +32,12 @@ Security Scan - - Coverage - License - - Conventional Commits - Ruff - - Stars - - - Forks - - - Issues - Last Commit @@ -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- -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 ` | 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 . - ---- - -## 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.