marketlab 0.1.0__tar.gz

marketlab-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ricardogr07
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

marketlab-0.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: marketlab
+Version: 0.1.0
+Summary: Reproducible market research toolkit for weekly modeling, walk-forward evaluation, and baseline-plus-ML experiments.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ricardogr07/market-lab
+Project-URL: Repository, https://github.com/ricardogr07/market-lab
+Project-URL: Issues, https://github.com/ricardogr07/market-lab/issues
+Keywords: market-research,backtesting,walk-forward,machine-learning,portfolio
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: pandas>=2.2
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: yfinance>=0.2
+Requires-Dist: scikit-learn>=1.4
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: mkdocs>=1.6; extra == "dev"
+Requires-Dist: mkdocs-include-markdown-plugin>=7.1; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.11; extra == "dev"
+Requires-Dist: tox>=4.0; extra == "dev"
+Dynamic: license-file
+
+# MarketLab
+
+MarketLab is a package-first research toolkit for reproducible market experiments over a fixed ETF universe. The current implementation includes a working baseline-plus-ML workflow: weekly supervised modeling rows, walk-forward folds, trained models, rank-based ML strategies, shared out-of-sample experiments, and reviewable artifact summaries.
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the system map, data contracts, execution flow, and extension rules.
+
+## Current Commands
+
+```bash
+python scripts/run_marketlab.py prepare-data --config configs/experiment.weekly_rank.yaml
+python scripts/run_marketlab.py backtest --config configs/experiment.weekly_rank.yaml
+python scripts/run_marketlab.py train-models --config configs/experiment.weekly_rank.yaml
+python scripts/run_marketlab.py run-experiment --config configs/experiment.weekly_rank.yaml
+```
+
+`python scripts/run_marketlab.py ...` is the canonical local invocation path because it always resolves to the source tree under `src/`.
+
+## What Each Command Does
+
+- `prepare-data`: build or reuse the cached prepared panel.
+- `backtest`: run the rule baselines only (`buy_hold` and `sma`) and write performance, analytics summaries, report, and plots.
+- `train-models`: fit the configured models across walk-forward folds and write raw training artifacts plus fold/model summary CSVs.
+- `run-experiment`: run baselines and ML strategies together on the shared out-of-sample window and write the experiment outputs, analytics summaries, and ML summary CSVs.
+
+## Artifact Outputs
+
+### `train-models`
+
+Writes a timestamped folder under `artifacts/runs/<experiment_name>/` containing:
+
+- `folds.csv`
+- `model_manifest.csv`
+- `model_metrics.csv`
+- `predictions.csv`
+- `model_summary.csv`
+- `fold_summary.csv`
+- per-fold model pickles under `models/`
+
+### `backtest`
+
+Writes a timestamped folder under `artifacts/runs/<experiment_name>/` containing:
+
+- `metrics.csv`
+- `performance.csv`
+- `strategy_summary.csv`
+- `monthly_returns.csv`
+- `turnover_costs.csv`
+- `report.md`
+- `cumulative_returns.png`
+- `drawdown.png`
+- `turnover.png`
+
+### `run-experiment`
+
+Writes a timestamped folder under `artifacts/runs/<experiment_name>/` containing:
+
+- `metrics.csv`
+- `performance.csv`
+- `strategy_summary.csv`
+- `monthly_returns.csv`
+- `turnover_costs.csv`
+- `report.md`
+- `cumulative_returns.png`
+- `drawdown.png`
+- `turnover.png`
+- `model_summary.csv`
+- `fold_summary.csv`
+- optional per-fold model pickles under `models/`
+
+## Environment
+
+- Python 3.12+
+- Installed packages:
+  - `pandas`
+  - `PyYAML`
+  - `matplotlib`
+  - `yfinance`
+  - `scikit-learn`
+
+## Quickstart
+
+```bash
+python -m pip install -e .[dev]
+python scripts/run_marketlab.py run-experiment --config configs/experiment.weekly_rank.yaml
+```
+
+If `artifacts/data/panel.csv` already exists, the pipeline uses it and does not attempt a network download.
+
+## Installed Package Quickstart
+
+If you install MarketLab from PyPI or a built wheel, use the packaged CLI bootstrap flow instead of the repo launcher:
+
+```bash
+marketlab --version
+marketlab list-configs
+marketlab write-config --name weekly_rank --output weekly_rank.yaml
+marketlab run-experiment --config weekly_rank.yaml
+```
+
+`list-configs` shows the bundled example templates, and `write-config` exports one of those templates into your working directory. That keeps the installed package self-contained without requiring a checkout of this repository.
+
+## Local Validation
+
+```bash
+python -m pytest -q --basetemp .pytest_tmp
+powershell -ExecutionPolicy Bypass -File scripts/run-e2e.ps1
+```
+
+## Local CI Entry Points
+
+```bash
+python -m uv sync --group dev
+python -m uv run tox -e lint
+python -m uv run tox -e docs
+python -m uv run tox -e package
+python -m uv run tox -e py312
+python -m tox -e integration
+python -m tox -e preflight
+```
+
+Use `python -m tox -e preflight` as the canonical local pre-push gate. It runs the same lint, docs, packaging, unit-test, and offline integration checks that Phase 3 CI expects through one local entrypoint after the dev dependencies are installed.
+
+The MkDocs site renders the current root Markdown docs through `mkdocs-include-markdown-plugin`, so the documentation build stays aligned with `README.md`, `ARCHITECTURE.md`, `Phase2-results.md`, and `PLAN.md`.
+
+## Contribution Workflow
+
+- Branch from a refreshed `master` instead of working directly on the default branch.
+- Keep changes in small intentional commits so review scope stays clear.
+- Run `python -m tox -e preflight` before pushing.
+- Open a pull request for review instead of pushing directly to `master`.
+- Treat the `Docker Runner` workflow as an optional manual smoke path, not as a required pre-push step.
+- Keep Codex skills and other personal automation assets in the user-local Codex home rather than in the public repository or package surface.
+- Expect `master` to move ahead of the last public release between monthly release batches.
+
+## Dockerized CLI
+
+```bash
+docker build -t marketlab-cli .
+docker run --rm marketlab-cli --help
+docker run --rm marketlab-cli backtest --config configs/experiment.weekly_rank.smoke.yaml
+```
+
+The container uses the installed `marketlab` console script as its entrypoint. Keep using `python scripts/run_marketlab.py ...` for local source-tree development; the Docker image exists to validate the installed package path and to support manual GitHub Actions runs.
+
+## Manual Docker Runner Workflow
+
+GitHub Actions now includes a manual workflow named `Docker Runner` with these inputs:
+
+- `command`: `backtest`, `train-models`, or `run-experiment`
+- `config_path`: repo-relative config path inside the image, defaulting to `configs/experiment.weekly_rank.smoke.yaml`
+
+The workflow defaults to `backtest`, builds the Docker image, runs the selected command inside the container, writes the resolved run directory into the job summary, and uploads the copied `artifacts/` tree as an Actions artifact.
+
+This workflow is not part of the required PR CI checks. It is a manual historical real-data smoke runner around the checked-in smoke config, not a rolling weekly market automation job.
+
+## Release Automation
+
+GitHub Actions now includes a release workflow at `.github/workflows/release.yml`.
+
+- Normal feature PRs still merge to `master` in sequence.
+- Each merge to `master` updates the open Release PR managed by release-please.
+- The Release PR accumulates the unreleased monthly or feature batch over time.
+- Nothing is tagged or published when a normal feature PR lands on `master`.
+- The actual Git tag, GitHub Release, and PyPI publish path run only when you merge the Release PR.
+
+This means `master` can intentionally contain unreleased work while you continue merging feature PRs. The Release PR is the public-release gate.
+
+### Manual Prerequisites
+
+Before the first automated public release:
+
+- verify that the `marketlab` package name is available on PyPI
+- configure PyPI Trusted Publishing for this repository and the `pypi` environment
+- create the GitHub Actions environment named `pypi`
+
+The first automated public release target remains `v0.1.0`.

marketlab-0.1.0/README.md

@@ -0,0 +1,176 @@
+# MarketLab
+
+MarketLab is a package-first research toolkit for reproducible market experiments over a fixed ETF universe. The current implementation includes a working baseline-plus-ML workflow: weekly supervised modeling rows, walk-forward folds, trained models, rank-based ML strategies, shared out-of-sample experiments, and reviewable artifact summaries.
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the system map, data contracts, execution flow, and extension rules.
+
+## Current Commands
+
+```bash
+python scripts/run_marketlab.py prepare-data --config configs/experiment.weekly_rank.yaml
+python scripts/run_marketlab.py backtest --config configs/experiment.weekly_rank.yaml
+python scripts/run_marketlab.py train-models --config configs/experiment.weekly_rank.yaml
+python scripts/run_marketlab.py run-experiment --config configs/experiment.weekly_rank.yaml
+```
+
+`python scripts/run_marketlab.py ...` is the canonical local invocation path because it always resolves to the source tree under `src/`.
+
+## What Each Command Does
+
+- `prepare-data`: build or reuse the cached prepared panel.
+- `backtest`: run the rule baselines only (`buy_hold` and `sma`) and write performance, analytics summaries, report, and plots.
+- `train-models`: fit the configured models across walk-forward folds and write raw training artifacts plus fold/model summary CSVs.
+- `run-experiment`: run baselines and ML strategies together on the shared out-of-sample window and write the experiment outputs, analytics summaries, and ML summary CSVs.
+
+## Artifact Outputs
+
+### `train-models`
+
+Writes a timestamped folder under `artifacts/runs/<experiment_name>/` containing:
+
+- `folds.csv`
+- `model_manifest.csv`
+- `model_metrics.csv`
+- `predictions.csv`
+- `model_summary.csv`
+- `fold_summary.csv`
+- per-fold model pickles under `models/`
+
+### `backtest`
+
+Writes a timestamped folder under `artifacts/runs/<experiment_name>/` containing:
+
+- `metrics.csv`
+- `performance.csv`
+- `strategy_summary.csv`
+- `monthly_returns.csv`
+- `turnover_costs.csv`
+- `report.md`
+- `cumulative_returns.png`
+- `drawdown.png`
+- `turnover.png`
+
+### `run-experiment`
+
+Writes a timestamped folder under `artifacts/runs/<experiment_name>/` containing:
+
+- `metrics.csv`
+- `performance.csv`
+- `strategy_summary.csv`
+- `monthly_returns.csv`
+- `turnover_costs.csv`
+- `report.md`
+- `cumulative_returns.png`
+- `drawdown.png`
+- `turnover.png`
+- `model_summary.csv`
+- `fold_summary.csv`
+- optional per-fold model pickles under `models/`
+
+## Environment
+
+- Python 3.12+
+- Installed packages:
+  - `pandas`
+  - `PyYAML`
+  - `matplotlib`
+  - `yfinance`
+  - `scikit-learn`
+
+## Quickstart
+
+```bash
+python -m pip install -e .[dev]
+python scripts/run_marketlab.py run-experiment --config configs/experiment.weekly_rank.yaml
+```
+
+If `artifacts/data/panel.csv` already exists, the pipeline uses it and does not attempt a network download.
+
+## Installed Package Quickstart
+
+If you install MarketLab from PyPI or a built wheel, use the packaged CLI bootstrap flow instead of the repo launcher:
+
+```bash
+marketlab --version
+marketlab list-configs
+marketlab write-config --name weekly_rank --output weekly_rank.yaml
+marketlab run-experiment --config weekly_rank.yaml
+```
+
+`list-configs` shows the bundled example templates, and `write-config` exports one of those templates into your working directory. That keeps the installed package self-contained without requiring a checkout of this repository.
+
+## Local Validation
+
+```bash
+python -m pytest -q --basetemp .pytest_tmp
+powershell -ExecutionPolicy Bypass -File scripts/run-e2e.ps1
+```
+
+## Local CI Entry Points
+
+```bash
+python -m uv sync --group dev
+python -m uv run tox -e lint
+python -m uv run tox -e docs
+python -m uv run tox -e package
+python -m uv run tox -e py312
+python -m tox -e integration
+python -m tox -e preflight
+```
+
+Use `python -m tox -e preflight` as the canonical local pre-push gate. It runs the same lint, docs, packaging, unit-test, and offline integration checks that Phase 3 CI expects through one local entrypoint after the dev dependencies are installed.
+
+The MkDocs site renders the current root Markdown docs through `mkdocs-include-markdown-plugin`, so the documentation build stays aligned with `README.md`, `ARCHITECTURE.md`, `Phase2-results.md`, and `PLAN.md`.
+
+## Contribution Workflow
+
+- Branch from a refreshed `master` instead of working directly on the default branch.
+- Keep changes in small intentional commits so review scope stays clear.
+- Run `python -m tox -e preflight` before pushing.
+- Open a pull request for review instead of pushing directly to `master`.
+- Treat the `Docker Runner` workflow as an optional manual smoke path, not as a required pre-push step.
+- Keep Codex skills and other personal automation assets in the user-local Codex home rather than in the public repository or package surface.
+- Expect `master` to move ahead of the last public release between monthly release batches.
+
+## Dockerized CLI
+
+```bash
+docker build -t marketlab-cli .
+docker run --rm marketlab-cli --help
+docker run --rm marketlab-cli backtest --config configs/experiment.weekly_rank.smoke.yaml
+```
+
+The container uses the installed `marketlab` console script as its entrypoint. Keep using `python scripts/run_marketlab.py ...` for local source-tree development; the Docker image exists to validate the installed package path and to support manual GitHub Actions runs.
+
+## Manual Docker Runner Workflow
+
+GitHub Actions now includes a manual workflow named `Docker Runner` with these inputs:
+
+- `command`: `backtest`, `train-models`, or `run-experiment`
+- `config_path`: repo-relative config path inside the image, defaulting to `configs/experiment.weekly_rank.smoke.yaml`
+
+The workflow defaults to `backtest`, builds the Docker image, runs the selected command inside the container, writes the resolved run directory into the job summary, and uploads the copied `artifacts/` tree as an Actions artifact.
+
+This workflow is not part of the required PR CI checks. It is a manual historical real-data smoke runner around the checked-in smoke config, not a rolling weekly market automation job.
+
+## Release Automation
+
+GitHub Actions now includes a release workflow at `.github/workflows/release.yml`.
+
+- Normal feature PRs still merge to `master` in sequence.
+- Each merge to `master` updates the open Release PR managed by release-please.
+- The Release PR accumulates the unreleased monthly or feature batch over time.
+- Nothing is tagged or published when a normal feature PR lands on `master`.
+- The actual Git tag, GitHub Release, and PyPI publish path run only when you merge the Release PR.
+
+This means `master` can intentionally contain unreleased work while you continue merging feature PRs. The Release PR is the public-release gate.
+
+### Manual Prerequisites
+
+Before the first automated public release:
+
+- verify that the `marketlab` package name is available on PyPI
+- configure PyPI Trusted Publishing for this repository and the `pypi` environment
+- create the GitHub Actions environment named `pypi`
+
+The first automated public release target remains `v0.1.0`.

marketlab-0.1.0/pyproject.toml

@@ -0,0 +1,86 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "marketlab"
+version = "0.1.0"
+description = "Reproducible market research toolkit for weekly modeling, walk-forward evaluation, and baseline-plus-ML experiments."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+keywords = ["market-research", "backtesting", "walk-forward", "machine-learning", "portfolio"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Financial and Insurance Industry",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Office/Business :: Financial :: Investment",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "matplotlib>=3.8",
+  "pandas>=2.2",
+  "PyYAML>=6.0",
+  "yfinance>=0.2",
+  "scikit-learn>=1.4",
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2",
+  "mkdocs>=1.6",
+  "mkdocs-include-markdown-plugin>=7.1",
+  "pytest>=8.0",
+  "ruff>=0.11",
+  "tox>=4.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/ricardogr07/market-lab"
+Repository = "https://github.com/ricardogr07/market-lab"
+Issues = "https://github.com/ricardogr07/market-lab/issues"
+
+[dependency-groups]
+dev = [
+  "build>=1.2",
+  "mkdocs>=1.6",
+  "mkdocs-include-markdown-plugin>=7.1",
+  "pytest>=8.0",
+  "ruff>=0.11",
+  "tox>=4.0",
+]
+
+[project.scripts]
+marketlab = "marketlab.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.package-data]
+"marketlab.resources.config_templates" = ["*.yaml"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.uv]
+default-groups = ["dev"]
+
+[tool.ruff]
+target-version = "py312"
+src = ["src", "tests", "scripts"]
+extend-exclude = ["artifacts", "build", "dist", "site", ".pytest_tmp*", "tmpk_x17fq8"]
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--basetemp=.pytest_tmp -p no:cacheprovider"
+markers = [
+  "real_data: opt-in tests that download real market data.",
+  "network: tests that depend on external network access.",
+]

marketlab-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

marketlab-0.1.0/src/marketlab/__init__.py

@@ -0,0 +1,5 @@
+"""MarketLab package for reproducible market experiments."""
+
+from marketlab._version import __version__
+
+__all__ = ["__version__"]

marketlab-0.1.0/src/marketlab/_version.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from importlib import metadata
+
+FALLBACK_VERSION = "0.0.0+local"
+DIST_NAME = "marketlab"
+
+
+def get_version(dist_name: str = DIST_NAME, fallback: str = FALLBACK_VERSION) -> str:
+    try:
+        return metadata.version(dist_name)
+    except metadata.PackageNotFoundError:
+        return fallback
+
+
+__version__ = get_version()

marketlab-0.1.0/src/marketlab/backtest/__init__.py

@@ -0,0 +1 @@
+"""Backtest engine and metrics."""

marketlab-0.1.0/src/marketlab/backtest/engine.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import pandas as pd
+
+
+def run_backtest(
+    panel: pd.DataFrame,
+    weights: pd.DataFrame,
+    cost_bps: float,
+) -> pd.DataFrame:
+    required_weight_columns = {"strategy", "effective_date", "symbol", "weight"}
+    missing = required_weight_columns - set(weights.columns)
+    if missing:
+        joined = ", ".join(sorted(missing))
+        raise ValueError(f"Weights frame is missing required columns: {joined}")
+
+    strategy_names = weights["strategy"].drop_duplicates().tolist()
+    if len(strategy_names) != 1:
+        raise ValueError("Backtest engine expects weights for exactly one strategy.")
+    strategy_name = strategy_names[0]
+
+    working_panel = panel.sort_values(["timestamp", "symbol"]).copy()
+    unique_dates = pd.Index(sorted(working_panel["timestamp"].drop_duplicates()))
+    symbols = sorted(working_panel["symbol"].unique())
+
+    adj_close = working_panel.pivot(index="timestamp", columns="symbol", values="adj_close")
+    adj_open = working_panel.pivot(index="timestamp", columns="symbol", values="adj_open")
+
+    overnight_returns = (adj_open / adj_close.shift(1)) - 1.0
+    intraday_returns = (adj_close / adj_open) - 1.0
+
+    weights_pivot = (
+        weights.copy()
+        .assign(effective_date=lambda frame: pd.to_datetime(frame["effective_date"]))
+        .pivot(index="effective_date", columns="symbol", values="weight")
+        .reindex(columns=symbols, fill_value=0.0)
+    )
+    weights_pivot = weights_pivot.reindex(unique_dates).ffill().fillna(0.0)
+
+    post_open_weights = weights_pivot
+    pre_open_weights = post_open_weights.shift(1).fillna(0.0)
+    turnover = (post_open_weights - pre_open_weights).abs().sum(axis=1)
+
+    gross_returns = (
+        (pre_open_weights * overnight_returns.fillna(0.0)).sum(axis=1)
+        + (post_open_weights * intraday_returns.fillna(0.0)).sum(axis=1)
+    )
+    costs = turnover * (cost_bps / 10_000.0)
+    net_returns = gross_returns - costs
+    equity = (1.0 + net_returns).cumprod()
+
+    return pd.DataFrame(
+        {
+            "date": unique_dates,
+            "strategy": strategy_name,
+            "gross_return": gross_returns.values,
+            "net_return": net_returns.values,
+            "turnover": turnover.values,
+            "equity": equity.values,
+        }
+    )

marketlab-0.1.0/src/marketlab/backtest/metrics.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import math
+
+import pandas as pd
+
+
+def compute_strategy_metrics(performance: pd.DataFrame) -> pd.DataFrame:
+    rows: list[dict[str, float | str]] = []
+    for strategy, frame in performance.groupby("strategy", sort=False):
+        ordered = frame.sort_values("date").reset_index(drop=True)
+        returns = ordered["net_return"]
+        equity = ordered["equity"]
+        periods = len(ordered)
+
+        cumulative_return = float(equity.iloc[-1] - 1.0) if periods else 0.0
+        annualized_return = (
+            float((equity.iloc[-1] ** (252.0 / periods)) - 1.0) if periods else 0.0
+        )
+        annualized_volatility = float(returns.std(ddof=0) * math.sqrt(252.0))
+        sharpe_like = (
+            annualized_return / annualized_volatility if annualized_volatility else 0.0
+        )
+        drawdown = (equity / equity.cummax()) - 1.0
+        max_drawdown = float(drawdown.min()) if not drawdown.empty else 0.0
+        hit_rate = float((returns > 0.0).mean()) if periods else 0.0
+        avg_turnover = float(ordered["turnover"].mean()) if periods else 0.0
+        total_turnover = float(ordered["turnover"].sum()) if periods else 0.0
+
+        rows.append(
+            {
+                "strategy": strategy,
+                "cumulative_return": cumulative_return,
+                "annualized_return": annualized_return,
+                "annualized_volatility": annualized_volatility,
+                "sharpe_like": sharpe_like,
+                "max_drawdown": max_drawdown,
+                "hit_rate": hit_rate,
+                "avg_turnover": avg_turnover,
+                "total_turnover": total_turnover,
+            }
+        )
+
+    return pd.DataFrame(rows)