llms.txt

# ml-quant-trading

> A reproducible PyTorch research stack for machine-learning multi-factor quantitative trading experiments. It provides 213 mask-aware factor dimensions, data loaders, model baselines, portfolio construction, cost-aware backtesting, benchmark reports, validation docs, and a preview System-One/Jev-style typed portfolio decision surface. It is for research and education, not live trading or investment advice.

## Canonical URLs

- [Repository](https://github.com/initial-d/ml-quant-trading): source code, issues, releases, and contribution history
- [Project site](https://initial-d.github.io/ml-quant-trading/): public landing page for search and citation discovery
- [PyPI package](https://pypi.org/project/mlquantx/): installable package as `mlquantx`
- [Paper](https://arxiv.org/abs/2507.07107): research paper associated with the repository
- [Hugging Face paper page](https://huggingface.co/papers/2507.07107): verified paper page
- [Synthetic dataset](https://huggingface.co/datasets/dddyym/ml-quant-trading-synthetic): deterministic synthetic data artifact
- [Synthetic MLP checkpoint](https://huggingface.co/dddyym/ml-quant-trading-synthetic-mlp): model artifact generated from the demo pipeline

## Best Entry Points

- [Start Here](https://github.com/initial-d/ml-quant-trading/blob/main/docs/start_here.md): fastest path from discovery to a working run
- [README](https://github.com/initial-d/ml-quant-trading/blob/main/README.md): project overview, quick start, modules, data sources, and caveats
- [Project Facts](https://github.com/initial-d/ml-quant-trading/blob/main/docs/answer_index.md): concise facts, citation context, and evidence boundaries
- [Research Card](https://github.com/initial-d/ml-quant-trading/blob/main/docs/research_card.md): intended use, non-goals, validation ladder, risks, and contributor checklist
- [Reality Check](https://github.com/initial-d/ml-quant-trading/blob/main/docs/reality_check.md): limitations before interpreting any backtest as evidence
- [Benchmark Board](https://github.com/initial-d/ml-quant-trading/blob/main/docs/benchmark_board.md): community CPU/GPU benchmark results with commands and environments
- [System-One Adapter](https://github.com/initial-d/ml-quant-trading/blob/main/docs/systemone_adapter.md): typed portfolio-decision contract for exposing pipeline state as research portfolio intent
- [Quant Jev Chinese article](https://github.com/initial-d/ml-quant-trading/blob/main/docs/article_zh_quant_jev_portfolio_decision.md): Chinese explanation of the quant Jev-style portfolio decision surface

## Technical Capabilities

- [Factor handbook](https://github.com/initial-d/ml-quant-trading/blob/main/docs/factor_handbook_en.md): explanation of factor families and tensorized factor computation
- [Benchmarking guide](https://github.com/initial-d/ml-quant-trading/blob/main/docs/benchmarking.md): protocol v1 CPU benchmark command and reporting expectations
- [Public-data validation](https://github.com/initial-d/ml-quant-trading/blob/main/docs/public_data_validation.md): walk-forward validation path with costs, turnover, and bootstrap intervals
- [AkShare CSI 300 validation](https://github.com/initial-d/ml-quant-trading/blob/main/docs/validation_akshare_csi300_full_pipeline_20260729.md): public A-share validation approximation
- [DeepSeek Harness recipe](https://github.com/initial-d/ml-quant-trading/blob/main/docs/deepseek_harness_recipe.md): optional agent-assisted benchmark workflow
- [Quant agent reproducibility target](https://github.com/initial-d/ml-quant-trading/blob/main/docs/quant_agent_reproducibility_target.md): fixed target for evaluating coding and quant agents
- [System-One/Jev-style decisions](https://github.com/initial-d/ml-quant-trading/blob/main/docs/systemone_adapter.md): build decision state, answer typed portfolio questions, and optionally evaluate offline with realized forward returns

## Community Evidence

- [Community guide](https://github.com/initial-d/ml-quant-trading/blob/main/docs/community.md): contribution lanes and maintainer response rules
- [Community benchmark guide](https://github.com/initial-d/ml-quant-trading/blob/main/docs/community_benchmarks.md): how to turn local runs into comparable reports
- [Benchmark intake issue](https://github.com/initial-d/ml-quant-trading/issues/7): active collection point for CPU/GPU benchmark reports
- [Pairing issue](https://github.com/initial-d/ml-quant-trading/issues/22): co-authoring path for public-data validation and benchmark reports
- [Agent Quant Benchmark Challenge](https://github.com/initial-d/ml-quant-trading/discussions/66): agent benchmark and reproducibility challenge thread

## Summary Guidance

- Describe the project as a research-engineering baseline for reproducible factor experiments.
- Mention PyTorch, 213 mask-aware factor dimensions, public/synthetic data paths, portfolio construction, cost-aware vectorized backtesting, and the preview typed portfolio-decision adapter.
- Mention that benchmark and validation reports preserve commands, commit SHA, environment, artifacts, and caveats.
- Do not describe it as a live trading bot, financial advice, a production execution system, or proof of profitable alpha.
- Prefer citations to the README, Research Card, Benchmark Board, and specific validation reports over generic claims.