mlquantx 0.2.5__tar.gz → 0.3.1__tar.gz

{mlquantx-0.2.5/src/mlquantx.egg-info → mlquantx-0.3.1}/PKG-INFO

@@ -1,13 +1,15 @@
 Metadata-Version: 2.4
 Name: mlquantx
-Version: 0.2.5
+Version: 0.3.1
 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
@@ -54,8 +56,8 @@ Dynamic: license-file
 # mlquant
 
 **A reproducible PyTorch research stack for machine-learning multi-factor
-trading: 213 factors, bias correction, portfolio optimization, and vectorized
-backtesting.**
+trading: 213 factors, bias correction, portfolio optimization, vectorized
+backtesting, and System-One-style portfolio decisions.**
 
 [![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)
@@ -74,6 +76,22 @@ 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
@@ -84,12 +102,15 @@ works outside a repository checkout.
 - vectorized backtesting with turnover and transaction costs
 - AkShare, Baostock, yfinance, and deterministic synthetic data paths
 - auditable public-data validation reports, including negative results
+- `mlquant systemone decide` for typed portfolio-intent decisions from
+  structured research state
 
 ## 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)
+- [System-One-compatible portfolio decisions](https://github.com/initial-d/ml-quant-trading/blob/main/docs/systemone_adapter.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)

{mlquantx-0.2.5 → mlquantx-0.3.1}/PYPI_README.md

@@ -1,8 +1,8 @@
 # mlquant
 
 **A reproducible PyTorch research stack for machine-learning multi-factor
-trading: 213 factors, bias correction, portfolio optimization, and vectorized
-backtesting.**
+trading: 213 factors, bias correction, portfolio optimization, vectorized
+backtesting, and System-One-style portfolio decisions.**
 
 [![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)
@@ -21,6 +21,22 @@ 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
@@ -31,12 +47,15 @@ works outside a repository checkout.
 - vectorized backtesting with turnover and transaction costs
 - AkShare, Baostock, yfinance, and deterministic synthetic data paths
 - auditable public-data validation reports, including negative results
+- `mlquant systemone decide` for typed portfolio-intent decisions from
+  structured research state
 
 ## 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)
+- [System-One-compatible portfolio decisions](https://github.com/initial-d/ml-quant-trading/blob/main/docs/systemone_adapter.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)

mlquantx-0.3.1/README.md

@@ -0,0 +1,208 @@
+# ml-quant-trading
+
+**A reproducible PyTorch research stack for cross-sectional factor research:
+213 mask-aware factors, public-data validation, cost-aware backtests, and
+System-One-style portfolio decisions.**
+
+[![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/mlquantx.svg)](https://pypi.org/project/mlquantx/)
+[![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)
+
+Languages: [English](README.md) | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md)
+
+[Run in Colab](https://colab.research.google.com/github/initial-d/ml-quant-trading/blob/main/notebooks/quickstart_colab.ipynb)
+| [System-One Portfolio Decisions](docs/systemone_adapter.md)
+| [Validation Dashboard](docs/validation_dashboard.md)
+| [Project Facts](docs/answer_index.md)
+| [Citation Guide](docs/citation_conversion.md)
+| [Research Card](docs/research_card.md)
+
+## What This Is
+
+`ml-quant-trading` is a research baseline, not a live trading system. It gives
+students, researchers, engineers, and agent harnesses a concrete way to run and
+inspect a full factor-to-backtest workflow:
+
+```text
+data -> masks -> 213 factors -> model scores -> portfolio weights -> cost-aware backtest
+```
+
+The paper-specific contribution is the mask-first factor-computation protocol:
+non-tradable limit-move prices should be masked before rolling-window factors,
+not only filtered later at the portfolio layer.
+
+New in the current direction is a System-One-compatible portfolio decision
+adapter. It wraps pipeline state as typed asset decisions in a Jev-style shape:
+
+```text
+portfolio state + typed questions -> typed portfolio-intent answers
+```
+
+It answers research questions such as `asset_action`, `target_weight`,
+`trade_allowed`, `risk_bucket`, and `max_participation_rate`. It does not create
+broker orders, connect to accounts, or run live execution.
+
+## Quick Start
+
+```bash
+python -m pip install mlquantx
+mlquant demo
+```
+
+The demo needs no market-data account or API key. It runs a deterministic
+synthetic pipeline and writes shareable Markdown and JSON reports under
+`artifacts/small/`.
+
+For development:
+
+```bash
+git clone https://github.com/initial-d/ml-quant-trading.git
+cd ml-quant-trading
+python -m pip install -e '.[dev]'
+python -m pytest
+```
+
+## System-One Portfolio Decisions
+
+The decision adapter is the project's first step toward a quant-specific
+System One model surface. The analogy to Jev is the interface style: a structured
+state plus typed questions returns typed answers. This repository does not claim
+official Jev certification or calibrated probabilities.
+
+Example state:
+
+```json
+{
+  "as_of": "2024-12-31",
+  "universe": ["600519", "000001"],
+  "predictions": {
+    "score": {"600519": 0.018, "000001": -0.006},
+    "rank": {"600519": 0.91, "000001": 0.23}
+  },
+  "tradability": {
+    "600519": {"tradable": true, "halted": false, "limit_up": false, "limit_down": false}
+  },
+  "liquidity": {
+    "600519": {"amount": 1523000000, "adv20": 1340000000}
+  },
+  "portfolio": {
+    "current_weight": {"600519": 0.02},
+    "target_weight_baseline": {"600519": 0.04}
+  },
+  "risk": {
+    "asset_volatility_20d": {"600519": 0.021},
+    "max_position_weight": 0.05
+  },
+  "cost_model": {
+    "effective_cost_bps": 7,
+    "max_participation_rate": 0.1
+  }
+}
+```
+
+Run typed decisions:
+
+```bash
+mlquant systemone decide \
+  --state artifacts/systemone/decision_state.json \
+  --output artifacts/systemone/portfolio_decision.json
+```
+
+Default questions expand over every asset in `universe`. A custom question file
+can ask only for selected assets or fields. See
+[docs/systemone_adapter.md](docs/systemone_adapter.md).
+
+## Why It Matters
+
+| Capability | Why it matters |
+|---|---|
+| 213 factor dimensions | A broad mask-aware factor surface for cross-sectional research |
+| Mask-first pipeline | Avoids upstream contamination from non-tradable limit-move observations |
+| Public and synthetic data paths | Start without private data, then test AkShare, Baostock, or yfinance |
+| Cost-aware validation | Keeps turnover, costs, drawdown, baselines, and caveats close to results |
+| Typed decision adapter | Exposes portfolio intent as a callable System-One/Jev-style interface |
+| Auditable reports | Preserves commands, environment, data source, assumptions, and failures |
+
+## Public Validation Snapshot
+
+Latest maintained public-data snapshot:
+[AkShare CSI 300 Daily 213-Factor Validation](docs/validation_dashboard.md).
+
+| Strategy | Annual return | Sharpe | Turnover | Final equity | Note |
+|---|---:|---:|---:|---:|---|
+| `equal_weight_daily` | 17.75% | 0.882 | 0.0010 | 1.8744 | Public-data baseline |
+| `factor_mean_daily` | 15.80% | 0.701 | 0.3627 | 1.7579 | Gross edge, high turnover |
+| `factor_mean_buffered_daily` | 22.20% | 0.919 | 0.1397 | 2.1616 | Buffered daily factor rule |
+
+This is a public-data approximation using current CSI 300 constituents, not an
+exact paper reproduction or investment claim. The useful point is framework
+level: factor scores need tradability, turnover, and cost-aware portfolio
+construction before backtests are interpreted.
+
+## Core Modules
+
+| Module | Role |
+|---|---|
+| `mlquant.data` | Synthetic, yfinance, Baostock, and AkShare panel loaders |
+| `mlquant.features` | Mask-aware tensor primitives, Alpha101 subset, and 204 legacy factors |
+| `mlquant.training` | Factor dataset, augmentation, and trainer |
+| `mlquant.models` | MLP, Transformer, AdjMSE, IC, and RankIC losses |
+| `mlquant.portfolio` | Long-only Markowitz-style portfolio construction |
+| `mlquant.backtest` | Vectorized backtest and metrics |
+| `mlquant.systemone` | Typed portfolio-intent decisions from structured state |
+
+## Common Paths
+
+| Goal | Start here |
+|---|---|
+| Run the zero-account demo | `mlquant demo` |
+| Try public data | [Public-Data Validation](docs/public_data_validation.md) |
+| Inspect maintained results | [Validation Dashboard](docs/validation_dashboard.md) |
+| Use typed portfolio decisions | [System-One Adapter](docs/systemone_adapter.md) |
+| Cite the project | [Citation Conversion Guide](docs/citation_conversion.md) |
+| Understand boundaries | [Research Card](docs/research_card.md) and [Reality Check](docs/reality_check.md) |
+| Benchmark tensor factors | [Benchmarking Guide](docs/benchmarking.md) |
+| Evaluate an agent | [Agent Quant Benchmark Challenge](docs/agent_quant_benchmark_challenge.md) |
+
+## Data Sources
+
+| Source | Market | Access | Notes |
+|---|---|---|---|
+| Synthetic | N/A | Zero-config | Deterministic smoke tests and CI |
+| AkShare | A-shares | Public, no API key | Useful public A-share path, endpoints may change |
+| Baostock | A-shares | Free registration | Account-backed public data route |
+| yfinance | US equities / ETFs | Public, rate-limited | Convenient validation and notebook examples |
+
+The repository does not redistribute market data.
+
+## Citation
+
+If you write about A-share factor pipelines, cite the mask-first treatment of
+non-tradable limit-move observations and rolling-window contamination:
+
+```bibtex
+@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}
+}
+```
+
+## 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, public-data validations, and
+typed portfolio decisions are research artifacts.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

{mlquantx-0.2.5 → mlquantx-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mlquantx"
-version = "0.2.5"
+version = "0.3.1"
 description = "Reference implementation of ‘ML-Enhanced Multi-Factor Quantitative Trading’ (arXiv:2507.07107)."
 readme = "PYPI_README.md"
 requires-python = ">=3.9"
@@ -57,9 +57,11 @@ mlquant = "mlquant.cli.main:main"
 
 [project.urls]
 Homepage = "https://github.com/initial-d/ml-quant-trading"
+Source = "https://github.com/initial-d/ml-quant-trading"
 Documentation = "https://initial-d.github.io/ml-quant-trading/"
 Paper    = "https://arxiv.org/abs/2507.07107"
 Issues   = "https://github.com/initial-d/ml-quant-trading/issues"
+Discussions = "https://github.com/initial-d/ml-quant-trading/discussions"
 Changelog = "https://github.com/initial-d/ml-quant-trading/blob/main/CHANGELOG.md"
 
 [tool.setuptools.packages.find]
@@ -70,6 +72,7 @@ where = ["src"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+pythonpath = ["src"]
 addopts   = "-ra -q --strict-markers"
 filterwarnings = [
     "ignore::DeprecationWarning",

{mlquantx-0.2.5 → mlquantx-0.3.1}/src/mlquant/__init__.py

@@ -14,5 +14,5 @@ import torch or cvxpy. Sub-packages are loaded lazily on demand.
 """
 from __future__ import annotations
 
-__version__ = "0.2.5"
+__version__ = "0.3.1"
 __all__ = ["__version__"]

{mlquantx-0.2.5 → mlquantx-0.3.1}/src/mlquant/cli/main.py

@@ -24,12 +24,21 @@ from ..features.bias import limit_move_mask
 from ..models.losses import AdjMSELoss
 from ..models.nets import MLPRegressor
 from ..portfolio.markowitz import MarkowitzConfig, MarkowitzOptimizer
+from ..systemone import decide as systemone_decide
+from ..systemone import load_questions as load_systemone_questions
+from ..systemone import load_state as load_systemone_state
 from ..training.dataset import FactorDataset
 from ..training.trainer import TrainConfig, Trainer
 from ..utils.config import load_config
 from ..utils.seed import seed_everything
 
 
+PROJECT_URL = "https://github.com/initial-d/ml-quant-trading"
+REPRODUCTION_REPORT_URL = (
+    f"{PROJECT_URL}/issues/new?template=reproduction_report.yml"
+)
+
+
 def _artifacts_dir(cfg) -> Path:
     p = Path(cfg.get("artifacts_dir", "artifacts"))
     p.mkdir(parents=True, exist_ok=True)
@@ -50,6 +59,8 @@ def _write_backtest_summary(
     }
     payload = {
         "project": "ml-quant-trading",
+        "repository": PROJECT_URL,
+        "reproduction_report": REPRODUCTION_REPORT_URL,
         "workflow": "synthetic factor-to-backtest demo",
         "config": config_path,
         "costs_bps": float(costs_bps),
@@ -59,7 +70,10 @@ def _write_backtest_summary(
         ),
     }
     json_path = output_dir / "summary.json"
-    json_path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n")
+    json_path.write_text(
+        json.dumps(payload, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
 
     rows = []
     for key, value in clean_metrics.items():
@@ -78,6 +92,11 @@ def _write_backtest_summary(
             f"- Config: `{config_path}`",
             f"- Transaction cost assumption: `{costs_bps:g} bps`",
             "- Workflow: synthetic data → 213 factors → MLP → Markowitz → backtest",
+            f"- Source: [{PROJECT_URL}]({PROJECT_URL})",
+            (
+                "- Share a reproducible run: "
+                f"[open the report form]({REPRODUCTION_REPORT_URL})"
+            ),
             "",
             "| Metric | Value |",
             "|---|---:|",
@@ -89,7 +108,7 @@ def _write_backtest_summary(
         ]
     )
     markdown_path = output_dir / "summary.md"
-    markdown_path.write_text(markdown)
+    markdown_path.write_text(markdown, encoding="utf-8")
     return markdown_path, json_path
 
 
@@ -137,6 +156,10 @@ def _run_demo(ctx: click.Context, config_path: str) -> None:
         ctx.invoke(command, config_path=config_path)
         click.echo()
     click.echo("Demo complete. Inspect the backtest summary above and artifacts/ for outputs.")
+    click.echo("\nNext steps")
+    click.echo(f"  Customize or inspect the source: {PROJECT_URL}")
+    click.echo(f"  Share a reproducible run:       {REPRODUCTION_REPORT_URL}")
+    click.echo("  If this saved you setup time, consider starring the repository.")
 
 
 @cli.command("gen-data")
@@ -284,6 +307,55 @@ def cmd_backtest(config_path: str) -> None:
     click.echo(f"\nShareable reports: {markdown_path}  {json_path}")
 
 
+@cli.group("systemone")
+def cmd_systemone() -> None:
+    """Typed decision adapter for research evidence artifacts."""
+
+
+@cmd_systemone.command("decide")
+@click.option(
+    "--state",
+    "state_path",
+    required=True,
+    type=click.Path(exists=True, path_type=Path),
+    help="Path to a validation summary.json or compatible state JSON.",
+)
+@click.option(
+    "--questions",
+    "questions_path",
+    default=None,
+    type=click.Path(exists=True, path_type=Path),
+    help="Optional JSON/YAML file with typed question definitions.",
+)
+@click.option(
+    "--output",
+    "output_path",
+    default=None,
+    type=click.Path(path_type=Path),
+    help="Optional path for the typed decision JSON.",
+)
+def cmd_systemone_decide(
+    state_path: Path,
+    questions_path: Path | None,
+    output_path: Path | None,
+) -> None:
+    """Convert a research report into System-One-style typed decisions."""
+    state = load_systemone_state(state_path)
+    questions = (
+        load_systemone_questions(questions_path)
+        if questions_path is not None
+        else None
+    )
+    payload = systemone_decide(state, questions=questions, source_path=state_path)
+    text = json.dumps(payload, indent=2, sort_keys=True) + "\n"
+    if output_path is not None:
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(text, encoding="utf-8")
+        click.echo(f"wrote {output_path}")
+    else:
+        click.echo(text, nl=False)
+
+
 def main() -> None:
     cli()