ml-quant-trading

ml-quant-trading

A reproducible PyTorch research stack for cross-sectional factor research: 213 mask-aware factors, public-data validation, cost-aware backtests, auditable reports, and a preview typed portfolio-decision adapter.

Languages: English | 简体中文 | 繁體中文

Run in Colab · Project Facts · How to Cite · Agent Benchmark Challenge · Validation Dashboard · Benchmark Board · Share This Project · Run with DSH · Decision Adapter · Quant Jev Article · Read the Paper

Quick Start

python -m pip install mlquantx
mlquant demo

No market-data account or API key is required. The deterministic demo runs the full research pipeline in about 30-90 seconds on a typical CPU-only laptop and writes shareable Markdown and JSON reports under artifacts/small/.

Returning after an earlier release? Upgrade with python -m pip install --upgrade mlquantx. The v0.4.1 release masks limit-move observations before rolling factors and measures returns across zero-filled halts from the last tradable close. Version v0.4.0 also moved demo evaluation to a held-out chronological window and made public-data dependencies optional. Install python -m pip install --upgrade 'mlquantx[data]' for public loaders; re-run older A-share or halt-bearing reports. These are correctness changes, not new trading-performance evidence.

data -> masks -> 213 factors -> model scores -> portfolio weights -> cost-aware backtest

Typical successful output includes:

wrote artifacts/small/panel.pt  (500 dates x 200 stocks)
wrote features: torch.Size([500, 200, 213])
wrote predictions: torch.Size([500, 200])
wrote weights: (500, 200)

Backtest summary

For development:

git clone https://github.com/initial-d/ml-quant-trading.git
cd ml-quant-trading
python -m pip install -e '.[dev]'
python -m pytest

Once it runs, you can inspect the benchmark or share a reproduction report. If the baseline is useful, a Star helps other researchers find it. Evaluating privately? Use the private evaluation checklist or submit a redacted evaluation note without exposing proprietary data, positions, or strategy details. For public reports, follow the reproducibility contract so results remain auditable after the original run.

See the benchmark board for complete environments, commands, and raw results. Cross-machine snapshots are reported separately and are not presented as controlled hardware rankings.

Why This Repository?

ml-quant-trading is a reproducible quant research baseline, not a live trading system. It gives students, researchers, engineers, and agent harnesses a concrete way to inspect and extend a full factor-to-backtest workflow:

The mask-first protocol propagates a chosen exclusion policy through rolling factor windows. An observed price at a limit can still be valid for a return label or held-position P&L; see the mask contract. Use the citation conversion guide with that implementation boundary in mind.

Try the live Hugging Face artifacts: the 100,000-row synthetic dataset and 213-input MLP checkpoint. Both come from the deterministic quick start and explicitly exclude real and proprietary market data; see the artifact guide.

Ready to modify factors, models, data sources, or backtest assumptions? Install from a source checkout:

git clone https://github.com/initial-d/ml-quant-trading.git
cd ml-quant-trading
python -m pip install -e '.[dev]'

Fast Path

Validation Dashboard

Archived public-data snapshot (2026-07-29, before v0.4.1): AkShare CSI 300 Daily 213-Factor Validation.

The numbers below predate the v0.4.1 mask-first and halt-safe return fixes. They remain historical records and have not been revalidated with the corrected protocol. The October 17 audit also found next-day availability entering portfolio selection through v0.4.1; revalidation requires that correction too. The detailed dashboard includes the protocol note, cost-sensitivity charts, and reproduction commands.

Strategy table from that archived snapshot:

The useful takeaway is framework-level: factor scores need tradability, turnover, and cost-aware portfolio construction before public-data backtests are interpreted. This is a public-data approximation using current CSI 300 constituents, not an exact paper reproduction or investment claim.

Acknowledgement: the AkShare zero-auth A-share data path was added through contributor work from @redamancy231-create in PR #42.

Community Evidence

Independent results are linked to pull requests, issues, or discussions so the environment, commands, limitations, and review history remain inspectable.

This repository is validation-first: simple baselines, transaction costs, public-data failure modes, and negative results are documented alongside the research pipeline. Successful and failed runs are both useful when the command, environment, data source, and limitations are preserved.

Want to add another machine, universe, or provider route? Run the zero-account Colab, then submit the generated report through the structured form.

DeepSeek Harness users can install the optional benchmark plugin, which is listed in Awesome DSH Plugin, then submit a structured DSH benchmark report.

Other current calls for contributors

• Try the v0.4.1 release.
• Read the Research Card for intended use, current evidence, and non-goals.
• Read the public-data mini reproduction.
• Share benchmark or public-data results in Discussions #13.
• Join the Agent Quant Benchmark Challenge with a coding agent, quant agent, DSH run, or redacted private evaluation.
• Pick up a newcomer task: more benchmark reports or a paired public-data validation or benchmark contribution.
• Read the Reality Check and Validation Status before interpreting any backtest as evidence of deployable alpha.

Core Modules

Data Sources

The repository does not redistribute market data. AkShare, Baostock, and yfinance data are downloaded on demand by the loader scripts. Public upstream interfaces can change or rate-limit requests. Synthetic data is generated deterministically from a fixed seed.

Example data loaders:

from mlquant.data import make_panel

panel = make_panel(
    source="akshare",
    tickers=["600519", "000001"],
    start="2020-01-01",
    end="2023-12-31",
    adjust="qfq",
)

from mlquant.data import make_panel

panel = make_panel(
    source="baostock",
    tickers=["sh.600000", "sz.000001"],
    start="2020-01-01",
    end="2023-12-31",
)

from mlquant.data import make_panel

panel = make_panel(
    source="yfinance",
    tickers=["SPY", "QQQ", "IWM"],
    start="2020-01-01",
    end="2023-12-31",
)

Installation And Demos

Install the published package:

python -m pip install mlquantx

# One-command smoke test: synthetic data, no API key required.
mlquant demo

The command prints a stage-by-stage run and writes shareable artifacts/small/summary.md and summary.json reports alongside model and backtest artifacts. The demo is a deterministic engineering smoke test, not a performance claim.

Install from source for development or optional extras:

git clone https://github.com/initial-d/ml-quant-trading.git
cd ml-quant-trading
python -m pip install -e '.[dev]'  # add ,gpu for CUDA; add ,mosek for MOSEK solver

The public-data loaders (AkShare, Baostock, yfinance) live in the data extra: python -m pip install 'mlquantx[data]'. The dev extra already includes it.

Google Colab Quick Start

Run the deterministic end-to-end pipeline in Google Colab without a market-data account or local setup:

The account-based Baostock A-share notebook remains available for users who want that data route.

Public-Data Validation

For a lightweight public-data walkthrough, open notebooks/public_factor_ic.ipynb. It downloads a small yfinance universe, computes a factor subset, and plots one-day forward rank IC. If public data download fails, the notebook falls back to the synthetic panel so the workflow remains runnable.

For a larger public-data validation run with walk-forward baselines, costs, slippage, cost-sensitivity reports, optional bootstrap confidence intervals, turnover, drawdown, and equal-weight / momentum / Alpha101 / MLP / Transformer comparisons:

python scripts/public_data_validation.py \
  --source yfinance \
  --preset us-large-100 \
  --max-tickers 100

See docs/public_data_validation.md. Treat these runs as validation diagnostics, not trading recommendations. The script writes summary.md, summary.csv, summary.json, metadata.json, and a copy-ready submission.md for community reports. Add --cost-grid-bps 0,7,15,30 to generate cost_sensitivity.* files, and add --bootstrap-samples 500 to include return and Sharpe uncertainty intervals. Maintainers can aggregate multiple summary.json files with scripts/aggregate_validation_reports.py and audit individual reports with scripts/audit_validation_report.py.

Tensor Factor Benchmark

Canonical protocol v1 CPU benchmark:

python scripts/benchmark_tensor_factors.py \
  --device cpu --n-dates 750 --n-stocks 1000 --window 20 \
  --repeat 10 --warmup 3 --threads 1 --interop-threads 1 --seed 42 \
  --json-out artifacts/benchmark-v1.json

On systems with GNU Make:

make benchmark

See docs/benchmarking.md for larger-panel commands and reporting guidance. Benchmark reports from different machines are welcome through the Benchmark result issue template. CPU/GPU benchmarks are engineering diagnostics, not trading performance evidence.

Reproducible Dev Environment

For a Docker-based CPU environment:

docker build -t ml-quant-trading .
docker run --rm ml-quant-trading make test

See docs/docker.md for Docker benchmark, synthetic pipeline, and public-data validation commands.

For VS Code or GitHub Codespaces, use the included Dev Container:

.devcontainer/devcontainer.json

It installs Python 3.11 and the project with python -m pip install -e '.[dev]'.

Factor Library

The full feature set comprises 9 curated Alpha101 formulas (features.alpha101) plus 204 hand-crafted legacy factors (features.legacy_factors) for a total of 213 dimensions. All factors are mask-aware PyTorch tensors with signature Panel -> (values[T,N], mask[T,N]).

Factor handbook: English · 中文. The handbook records design notes and implementation rationale for each factor family.

Usage:

from mlquant.features import compute_legacy_set

# Compute all 213 factors: 204 legacy + 9 Alpha101.
factors, mask, names = compute_legacy_set(panel)  # -> [T, N, 213]

# Or compute a named subset.
factors, mask, names = compute_legacy_set(
    panel,
    names=("best_001", "add_015", "old_042"),
)

add_001    add_002    add_003    add_004    add_005    add_006
add_007    add_008    add_009    add_010    add_011    add_012
add_013    add_014    add_015    add_016    add_017    add_018
add_019    add_020    add_021    add_022    add_023    add_024
add_025    add_026    add_027    add_028    add_029    add_030
best_001   best_002   best_003   best_004   best_005   best_006
best_007   best_008   best_009   best_010   best_011   best_012
best_013   best_014   best_015   best_016   best_017   best_018
best_019   best_020   best_021
change_001 change_002 change_003 change_004 change_005
extra_001  extra_002  extra_003  extra_004  extra_005  extra_006
extra_007  extra_008  extra_009  extra_010  extra_011  extra_012
extra_013  extra_014
old_027    old_028    old_029    old_030    old_031    old_032
old_033    old_034    old_035    old_036    old_037    old_038
old_039    old_040    old_041    old_042    old_043    old_044
old_045    old_046    old_047    old_048    old_049    old_050
old_051    old_052    old_053    old_054    old_055    old_056
old_057    old_058    old_059    old_060    old_061    old_062
old_063    old_064    old_065    old_066    old_067    old_068
old_069    old_070    old_071    old_072    old_073    old_074
old_075    old_076
original_001 original_002 original_003 original_004 original_005
original_006 original_007 original_008 original_009 original_010
original_011 original_012 original_013 original_014 original_015
original_016 original_017 original_018 original_019 original_020
original_021 original_022 original_023 original_024 original_025
original_026 original_027 original_028
stock_001  stock_002  stock_003  stock_004  stock_005  stock_006
stock_007  stock_008  stock_009  stock_010  stock_011  stock_012
stock_013  stock_014  stock_015  stock_016  stock_017  stock_018
stock_019  stock_020  stock_021  stock_022

Architecture

Solid arrows are the default research pipeline. The decision adapter is a typed research interface over pipeline state; it is not broker, order, or execution infrastructure.

Portfolio Decision Adapter

Version v0.3.1 adds a preview System-One-compatible portfolio-decision adapter. This is intentionally positioned as an interface layer over the research pipeline, not as the main claim of the repository.

The useful framing is:

pipeline state + typed portfolio questions -> typed portfolio-intent answers

The state can contain factor values, masks, model predictions, current weights, baseline target weights, tradability flags, liquidity, risk estimates, and cost assumptions. Questions are typed portfolio questions such as:

• should this asset be increased, held, decreased, or excluded?
• what is the research target weight?
• is this asset allowed by tradability and risk checks?
• what risk bucket should be assigned?
• what maximum participation rate is reasonable for the research simulation?

Run the adapter:

mlquant systemone build-state \
  --artifacts-dir artifacts/small \
  --as-of-index -2 \
  --output artifacts/systemone/decision_state.json

mlquant systemone decide \
  --state artifacts/systemone/decision_state.json \
  --output artifacts/systemone/portfolio_decision.json

If no question file is supplied, the adapter expands the default question set over every asset in universe. A custom question file can ask only for selected assets or fields. See docs/systemone_adapter.md for the state contract, question schema, and output shape.

The Jev comparison is about interface shape: a structured state plus typed questions returns typed answers. This repository does not claim official Jev integration, Jev certification, externally hosted inference, or calibrated probabilities. It also does not create broker orders, connect to accounts, run live services, or change the paper’s validation claims.

For offline scoring, rebuild the state with --include-realized and run:

mlquant systemone evaluate \
  --state artifacts/systemone/decision_state_eval.json \
  --decision artifacts/systemone/portfolio_decision.json \
  --output artifacts/systemone/portfolio_decision_eval.json

The evaluator reports action-label accuracy, target-weight forward return, turnover, estimated one-period cost, and hindsight regret. Those metrics are diagnostics for the typed decision surface; they are not live trading evidence.

Project Layout

ml-quant-trading/
├── src/mlquant/
│   ├── data/           # Panel dataclass, loaders, synthetic generator
│   ├── features/       # Tensor factor engine, 204 legacy factors, Alpha101
│   ├── training/       # Dataset, augmentation, trainer
│   ├── models/         # MLP, Transformer, losses
│   ├── portfolio/      # Markowitz, frontier sweep
│   ├── backtest/       # Engine, metrics
│   ├── systemone.py    # Typed portfolio decision adapter
│   └── cli/            # Command-line interface
├── configs/            # small.yaml (smoke) / paper.yaml (full)
├── tests/              # pytest suite
├── scripts/            # validation, benchmark, and reporting utilities
├── legacy/             # Original research scripts: archival, unsupported
└── docs/               # Architecture, validation, benchmark, release docs

Reproducing The Paper

See docs/reproducing_paper.md for the table-by-table mapping. Community benchmark and reproduction reports are welcome; when sharing results, preserve the command, commit SHA, environment, data source, cost assumptions, and limitations.

Roadmap

See docs/roadmap.md for contributor-friendly tasks, research extensions, engineering extensions, and community milestones.

For paper-specific positioning, see the Citation Conversion Guide. Maintainer launch and release notes live in docs/maintainer/.

Boundary

This project is for research and engineering experimentation. It is not financial advice, not investment advice, not a broker-connected system, and not a claim of live deployable alpha. Synthetic demos, CPU/GPU benchmarks, public-data smoke tests, public-data validations, and typed portfolio decisions are research artifacts.

Backtest results depend on data quality, survivorship assumptions, transaction costs, slippage, liquidity, capacity, execution timing, and modeling choices. Read docs/reality_check.md before interpreting any backtest as evidence of deployable alpha.

Contributing

Contributions are welcome, especially docs, reproducibility notes, tests, data adapters, benchmark reports, validation reports, and small examples. See CONTRIBUTING.md for setup and pull request guidance.

One useful contribution can be as simple as running the zero-account Colab and submitting the generated report through the structured reproduction form.

Citation

If you write about A-share factor pipelines, cite the mask-first treatment of non-tradable limit-move observations and rolling-window contamination:

@article{du2025mlquant,
  title  = {Machine Learning Enhanced Multi-Factor Quantitative Trading:
            A Cross-Sectional Portfolio Optimization Approach with Bias Correction},
  author = {Du, Yimin},
  journal= {arXiv preprint arXiv:2507.07107},
  year   = {2025},
  doi    = {10.48550/arXiv.2507.07107},
  url    = {https://arxiv.org/abs/2507.07107}
}

License

MIT. See LICENSE.