initial-d · initial-d · Aug 8, 2026 · Aug 8, 2026
diff --git a/.zenodo.json b/.zenodo.json
@@ -1,7 +1,7 @@
 {
   "title": "ml-quant-trading: Machine Learning Enhanced Multi-Factor Quantitative Trading",
   "upload_type": "software",
-  "publication_date": "2026-07-20",
+  "publication_date": "2026-08-08",
   "creators": [
     {
       "name": "Du, Yimin"

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+## 0.2.5 - Portable Packaging and Reproducibility Artifacts
+
+This release makes the zero-account demo portable beyond a source checkout and
+publishes the project as an installable Python distribution. It also packages
+the reproducibility artifacts added after v0.2.4.
+
+### Packaging and first run
+
+- Packaged the deterministic small demo config inside the `mlquant` wheel.
+- Made `mlquant demo` resolve its bundled config when `--config` is omitted, so
+  it can run from any working directory after installation.
+- Preserved explicit `--config PATH` behavior for repository and custom runs.
+- Added regression coverage for isolated-directory execution and configuration
+  synchronization.
+- Modernized package license metadata for current PyPI tooling.
+
 ### Hugging Face artifacts
 
 - Added a deterministic exporter for a viewer-ready synthetic OHLCV dataset and
@@ -10,6 +26,14 @@
   safety boundary that rejects non-synthetic configs.
 - Documented the authenticated upload and post-upload verification workflow.
 
+### Documentation and contributor evidence
+
+- Linked the live Hugging Face dataset and model to the paper metadata.
+- Refreshed the Chinese project landing page with downloadable artifacts,
+  v0.2.4 metric-clarity context, and contributor credit.
+- Kept the public-data and synthetic-artifact boundaries explicit: the packaged
+  demo and Hugging Face artifacts are reproducibility aids, not alpha claims.
+
 ## 0.2.4 - Metric Clarity and Contributor-Led Review
 
 This patch release turns an external review finding into a clearer reporting

diff --git a/CITATION.cff b/CITATION.cff
@@ -8,8 +8,8 @@ authors:
 repository-code: "https://github.com/initial-d/ml-quant-trading"
 url: "https://github.com/initial-d/ml-quant-trading"
 license: MIT
-version: "0.2.0"
-date-released: "2026-07-20"
+version: "0.2.5"
+date-released: "2026-08-08"
 abstract: "A research-oriented, end-to-end implementation of ML-enhanced multi-factor quantitative trading with tensor factor computation, bias correction, portfolio optimization, and backtesting."
 keywords:
   - quantitative-finance

diff --git a/PYPI_README.md b/PYPI_README.md
@@ -0,0 +1,55 @@
+# 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 mlquant
+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.
+
+## 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).
diff --git a/README.md b/README.md
@@ -10,6 +10,7 @@ vectorized backtesting, and auditable reports.
 [![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)
 [![GitHub stars](https://img.shields.io/github/stars/initial-d/ml-quant-trading?style=flat&logo=github&label=Stars)](https://github.com/initial-d/ml-quant-trading/stargazers)
 [![Release](https://img.shields.io/github/v/release/initial-d/ml-quant-trading?display_name=tag)](https://github.com/initial-d/ml-quant-trading/releases)
+[![PyPI](https://img.shields.io/pypi/v/mlquant.svg)](https://pypi.org/project/mlquant/)
 [![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/)
 [![MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
@@ -21,12 +22,11 @@ Languages: [English](README.md) | [简体中文](README.zh-CN.md) | [繁體中
 · [**See cost-aware results**](docs/validation_dashboard.md)
 · [**Read the paper**](https://arxiv.org/abs/2507.07107)
 
-> **New in v0.2.4 — a community review changed how we report trading costs.**
-> External contributor [@sergio12S](https://github.com/sergio12S) showed that
-> `cost_drag` was cumulative over a run while neighboring metrics were annualized.
-> The math was correct; the label made a wrong comparison too easy. Read the
-> [technical story](docs/backtest_cost_drag_story.md) or inspect
-> [PR #47](https://github.com/initial-d/ml-quant-trading/pull/47).
+> **New in v0.2.5 — install from PyPI and run from any directory.**
+> `mlquant demo` now ships with its deterministic configuration inside the
+> wheel, preserving the zero-account factor-to-backtest path after a regular
+> package install. The release also includes the live Hugging Face artifacts
+> and the v0.2.4 community-reviewed metric clarification.
 
 ---
 
@@ -49,9 +49,7 @@ proprietary market data; see the [artifact guide](docs/huggingface_artifacts.md)
 ## Quick Start
 
 ```bash
-git clone https://github.com/initial-d/ml-quant-trading.git
-cd ml-quant-trading
-python -m pip install -e '.[dev]'
+python -m pip install mlquant
 mlquant demo
 ```
 
@@ -117,7 +115,7 @@ Successful and failed runs are both useful and credited.
 **Other current calls for contributors**
 
 - Join the [August 2026 reproduction challenge](https://github.com/initial-d/ml-quant-trading/discussions/43): run Colab once, then use the [structured report form](https://github.com/initial-d/ml-quant-trading/issues/new?template=reproduction_report.yml), whether it succeeds or fails.
-- Try the [`v0.2.4` release](https://github.com/initial-d/ml-quant-trading/releases/tag/v0.2.4).
+- Try the [`v0.2.5` release](https://github.com/initial-d/ml-quant-trading/releases/tag/v0.2.5).
 - Read the [Research Card](docs/research_card.md) for intended use, current evidence, and non-goals.
 - Read the [public-data mini reproduction](docs/public_data_mini_reproduction.md).
 - Share benchmark or public-data results in [Discussions #13](https://github.com/initial-d/ml-quant-trading/discussions/13).
@@ -170,9 +168,7 @@ deterministically from a fixed seed.
 ## Installation and Demos
 
 ```bash
-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
+python -m pip install mlquant
 
 # One-command smoke test (synthetic data; no API key required)
 mlquant demo
@@ -183,6 +179,14 @@ The command prints a stage-by-stage run and writes shareable
 backtest artifacts. The demo is a deterministic engineering smoke test, not a
 performance claim.
 
+For development or optional extras, install from a source checkout:
+
+```bash
+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
+```
+
 ### Google Colab Quick Start
 
 Run the deterministic end-to-end pipeline in Google Colab without a market-data

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -10,6 +10,7 @@ Languages: [English](README.md) | [简体中文](README.zh-CN.md) | [繁體中
 [![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)
 [![GitHub stars](https://img.shields.io/github/stars/initial-d/ml-quant-trading?style=flat&logo=github&label=Stars)](https://github.com/initial-d/ml-quant-trading/stargazers)
 [![Release](https://img.shields.io/github/v/release/initial-d/ml-quant-trading?display_name=tag)](https://github.com/initial-d/ml-quant-trading/releases)
+[![PyPI](https://img.shields.io/pypi/v/mlquant.svg)](https://pypi.org/project/mlquant/)
 [![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
 [![MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
@@ -21,12 +22,9 @@ Languages: [English](README.md) | [简体中文](README.zh-CN.md) | [繁體中
 · [**阅读论文**](https://arxiv.org/abs/2507.07107)
 · [**提交一次复现报告**](https://github.com/initial-d/ml-quant-trading/issues/new?template=reproduction_report.yml)
 
-> **v0.2.4：一次外部评审改变了项目报告交易成本的方式。**
-> 社区贡献者 [@sergio12S](https://github.com/sergio12S) 指出，旧版 `cost_drag`
-> 表示整段回测的累计值，却与年化指标并列展示，容易被误读。计算本身没有错误，
-> 但报告契约不够清晰。新版改为显式字段 `cost_drag_cumulative`，同时保留兼容别名；
-> 完整讨论和验证见 [PR #47](https://github.com/initial-d/ml-quant-trading/pull/47)
-> 与[技术复盘](docs/backtest_cost_drag_story.md)。
+> **v0.2.5：项目正式提供 PyPI 安装。**执行 `pip install mlquant` 后，
+> 可以在任意目录运行 `mlquant demo`；确定性配置已随 wheel 打包，不再依赖源码目录。
+> 本版同时包含 Hugging Face 可下载产物，以及 v0.2.4 经社区评审的交易成本口径修正。
 
 > **2026 年 8 月复现挑战：**打开零账号 Colab 跑一次，把自动生成的报告、
 > 运行环境和 commit SHA 填入[结构化报告表单](https://github.com/initial-d/ml-quant-trading/issues/new?template=reproduction_report.yml)。
@@ -103,9 +101,7 @@ Languages: [English](README.md) | [简体中文](README.zh-CN.md) | [繁體中
 ## 快速开始
 
 ```bash
-git clone https://github.com/initial-d/ml-quant-trading.git
-cd ml-quant-trading
-python -m pip install -e '.[dev]'  # 如需 CUDA，请添加 ,gpu；如需 MOSEK solver，请添加 ,mosek
+python -m pip install mlquant
 
 # 一条命令跑通（Synthetic 数据，无需 API Key）
 mlquant demo
@@ -115,6 +111,14 @@ mlquant demo
 `summary.md` 与 `summary.json`，同时保留模型和回测产物。该 Demo 是确定性的
 工程冒烟测试，不是收益展示。
 
+如需参与开发或安装可选依赖，请使用源码模式：
+
+```bash
+git clone https://github.com/initial-d/ml-quant-trading.git
+cd ml-quant-trading
+python -m pip install -e '.[dev]'  # 如需 CUDA，请添加 ,gpu；如需 MOSEK solver，请添加 ,mosek
+```
+
 ### 公开数据验证（可选）
 
 轻量示例请打开 [`notebooks/public_factor_ic.ipynb`](notebooks/public_factor_ic.ipynb)。如需运行规模更大的 yfinance walk-forward 验证：

diff --git a/README.zh-TW.md b/README.zh-TW.md
@@ -46,14 +46,14 @@ Languages: [English](README.md) | [简体中文](README.zh-CN.md) | [繁體中
 ## 快速開始
 
 ```bash
-git clone https://github.com/initial-d/ml-quant-trading.git
-cd ml-quant-trading
-python -m pip install -e '.[dev]'  # 如需 CUDA，請加入 ,gpu；如需 MOSEK solver，請加入 ,mosek
+python -m pip install mlquant
 
-# 30 秒冒煙測試（Synthetic：200 檔股票 × 500 天）
-make paper CONFIG=configs/small.yaml
+# Synthetic 冒煙測試，無需行情帳號
+mlquant demo
 ```
 
+如需參與開發或安裝可選依賴，請 clone 原始碼並使用 `pip install -e '.[dev]'`。
+
 ### 公開資料驗證（選用）
 
 輕量範例請開啟 [`notebooks/public_factor_ic.ipynb`](notebooks/public_factor_ic.ipynb)。如需執行規模較大的 yfinance walk-forward 驗證：

diff --git a/docs/release_draft_v0.2.5.md b/docs/release_draft_v0.2.5.md
@@ -0,0 +1,31 @@
+# v0.2.5 - Portable Packaging and Reproducibility Artifacts
+
+`v0.2.5` is the first PyPI release of `mlquant`. It removes a subtle packaging
+trap: the command-line entry point was installable, but its default demo config
+previously lived only in a repository checkout. The deterministic config now
+ships inside the wheel, so a fresh environment can run the advertised demo from
+any working directory.
+
+## Highlights
+
+- Install directly with `python -m pip install mlquant`.
+- Run `mlquant demo` from any directory without cloning the repository.
+- Keep explicit `mlquant demo --config PATH` behavior for custom research runs.
+- Include the deterministic small config in the wheel and test it against the
+  repository copy.
+- Include the post-v0.2.4 Hugging Face dataset/model export and documentation.
+- Modernize license metadata for current PyPI build tooling.
+
+## Verification
+
+- Built both wheel and source distribution from a clean build environment.
+- Checked both distributions with `twine check --strict`.
+- Verified the wheel contains `mlquant/configs/small.yaml`.
+- Installed the wheel in an isolated environment outside the repository.
+- Passed CI on Python 3.9, 3.10, and 3.11, including the full CLI smoke test.
+
+## Research Boundary
+
+The bundled demo uses deterministic synthetic data. It verifies installation
+and the factor-to-backtest engineering path; it is not evidence of live or
+out-of-sample trading performance and is not investment advice.
diff --git a/docs/start_here.md b/docs/start_here.md
@@ -6,7 +6,7 @@ This page is the fastest path from discovering the repository to running somethi
 
 | If you are... | Start with |
 |---|---|
-| New to the project | `make paper CONFIG=configs/small.yaml` |
+| New to the project | `pip install mlquant && mlquant demo` |
 | A quant researcher | `notebooks/public_factor_ic.ipynb` |
 | An ML engineer | `make benchmark` |
 | A contributor | Issues labeled `good first issue` |
@@ -15,9 +15,7 @@ This page is the fastest path from discovering the repository to running somethi
 ## 2. Run the Small Pipeline
 
 ```bash
-git clone https://github.com/initial-d/ml-quant-trading.git
-cd ml-quant-trading
-python -m pip install -e '.[dev]'
+python -m pip install mlquant
 mlquant demo
 ```
 

diff --git a/pyproject.toml b/pyproject.toml
@@ -1,21 +1,21 @@
 [build-system]
-requires = ["setuptools>=68", "wheel"]
+requires = ["setuptools>=77", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "mlquant"
-version = "0.2.4"
+version = "0.2.5"
 description = "Reference implementation of ‘ML-Enhanced Multi-Factor Quantitative Trading’ (arXiv:2507.07107)."
-readme = "README.md"
+readme = "PYPI_README.md"
 requires-python = ">=3.9"
-license = { text = "MIT" }
+license = "MIT"
+license-files = ["LICENSE", "NOTICE.md"]
 authors = [{ name = "Yimin Du" }]
 keywords = ["quant", "alpha", "factor", "portfolio", "pytorch", "markowitz"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Financial and Insurance Industry",
     "Intended Audience :: Science/Research",
-    "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3 :: Only",
     "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",

diff --git a/src/mlquant/__init__.py b/src/mlquant/__init__.py
@@ -14,5 +14,5 @@
 """
 from __future__ import annotations
 
-__version__ = "0.2.4"
+__version__ = "0.2.5"
 __all__ = ["__version__"]