Metadata-Version: 2.4
Name: mlquantx
Version: 0.2.6
Summary: Reference implementation of ‘ML-Enhanced Multi-Factor Quantitative Trading’ (arXiv:2507.07107).
Author: Yimin Du
License-Expression: MIT
Project-URL: Homepage, https://github.com/initial-d/ml-quant-trading
Project-URL: Source, https://github.com/initial-d/ml-quant-trading
Project-URL: Documentation, https://initial-d.github.io/ml-quant-trading/
Project-URL: Paper, https://arxiv.org/abs/2507.07107
Project-URL: Issues, https://github.com/initial-d/ml-quant-trading/issues
Project-URL: Discussions, https://github.com/initial-d/ml-quant-trading/discussions
Project-URL: Changelog, https://github.com/initial-d/ml-quant-trading/blob/main/CHANGELOG.md
Keywords: quant,alpha,factor,portfolio,pytorch,markowitz
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE.md
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.10
Requires-Dist: scikit-learn>=1.3
Requires-Dist: torch>=2.0
Requires-Dist: cvxpy>=1.4
Requires-Dist: scs>=3.2
Requires-Dist: pyyaml>=6.0
Requires-Dist: click>=8.1
Requires-Dist: rich>=13.0
Requires-Dist: tqdm>=4.65
Requires-Dist: yfinance>=0.2.0
Requires-Dist: baostock>=0.8.8
Requires-Dist: akshare>=1.18.0
Provides-Extra: mosek
Requires-Dist: Mosek>=10.0; extra == "mosek"
Provides-Extra: ecos
Requires-Dist: ecos>=2.0; extra == "ecos"
Provides-Extra: gpu
Requires-Dist: cupy-cuda12x>=12.0; extra == "gpu"
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.7; extra == "dev"
Requires-Dist: hypothesis>=6.90; extra == "dev"
Dynamic: license-file

# mlquant

**A reproducible PyTorch research stack for machine-learning multi-factor
trading: 213 factors, bias correction, portfolio optimization, and vectorized
backtesting.**

[![CI](https://github.com/initial-d/ml-quant-trading/actions/workflows/ci.yml/badge.svg)](https://github.com/initial-d/ml-quant-trading/actions/workflows/ci.yml)
[![arXiv](https://img.shields.io/badge/arXiv-2507.07107-b31b1b.svg)](https://arxiv.org/abs/2507.07107)
[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)

## Install and run

```bash
python -m pip install mlquantx
mlquant demo
```

The demo needs no market-data account or API key. It runs the deterministic
synthetic pipeline from data generation through 213 factor dimensions, model
training, portfolio construction, cost-aware backtesting, and Markdown/JSON
report generation. The default config ships inside the wheel, so the command
works outside a repository checkout.

## Customize or contribute

The wheel is the fastest way to try the project. Clone the repository when you
want to change factors, models, portfolio constraints, data sources, or
backtest assumptions:

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

If the demo saves you setup time, consider
[starring the repository](https://github.com/initial-d/ml-quant-trading) or
[sharing a reproducible run](https://github.com/initial-d/ml-quant-trading/issues/new?template=reproduction_report.yml).

## What is included

- 204 hand-crafted factors plus 9 curated Alpha101-style factors
- mask-aware PyTorch tensor primitives for cross-sectional panels
- limit-up, limit-down, halt, and missing-data bias handling
- MLP and Transformer research baselines
- constrained Markowitz portfolio construction
- vectorized backtesting with turnover and transaction costs
- AkShare, Baostock, yfinance, and deterministic synthetic data paths
- auditable public-data validation reports, including negative results

## Start here

- [Source and full documentation](https://github.com/initial-d/ml-quant-trading)
- [Google Colab quick start](https://colab.research.google.com/github/initial-d/ml-quant-trading/blob/main/notebooks/quickstart_colab.ipynb)
- [Public validation dashboard](https://github.com/initial-d/ml-quant-trading/blob/main/docs/validation_dashboard.md)
- [Research card and limitations](https://github.com/initial-d/ml-quant-trading/blob/main/docs/research_card.md)
- [100,000-row synthetic dataset](https://huggingface.co/datasets/dddyym/ml-quant-trading-synthetic)
- [213-input MLP checkpoint](https://huggingface.co/dddyym/ml-quant-trading-synthetic-mlp)
- [Paper: arXiv:2507.07107](https://arxiv.org/abs/2507.07107)

## Research boundary

`mlquant` is research and educational software. It is not investment advice or
a production trading system. Synthetic smoke tests verify engineering behavior,
not profitability. Public-data backtests depend on data quality, survivorship,
transaction costs, slippage, and modeling assumptions and do not represent live
or guaranteed out-of-sample performance.

## License

MIT. See the [repository license](https://github.com/initial-d/ml-quant-trading/blob/main/LICENSE).
