Skip to content

"Vibe-Trading: Your Personal Trading Agent"

feat(factors): add research provenance contract

BHhhh-123cb803f9eb681
diff --git a/README.md b/README.md
index 9cdabb9d3..954a6972e 100644
--- a/README.md
+++ b/README.md
@@ -1537,6 +1537,22 @@ when the bench applies its protective one-bar lag; consumers must not treat
them as PIT-safe. New markets can register an adapter without changing this
wire shape.
+Bench results also carry `meta.research`, the versioned factor-research run
+contract (`factor-research.run/v1`). It records the declared research stage,
+factor IDs, input lineage, transformations and evaluation settings so a result
+can be traced from Alpha Zoo inputs through later research steps. The CLI can
+label a run with `--research-stage`, for example:
+
+```bash
+vibe-trading alpha bench --zoo gtja191 --universe csi300 --period 2018-2025 \
+ --research-stage factor_screening
+```
+
+The v1 contract is additive provenance metadata. Its `explore`, `strict` and
+`locked` values describe research intent; they do not by themselves reject
+unknown data or enforce a locked test set. Those checks remain separate from
+the existing availability contract until a future policy layer enables them.
+
**Browse the catalogue** and inspect a single alpha:
```bash
vibe-trading alpha list --zoo gtja191 --theme reversal --limit 10
diff --git a/agent/mcp_server.py b/agent/mcp_server.py
index 1ebd25a82..6a5b0ca57 100644
--- a/agent/mcp_server.py
+++ b/agent/mcp_server.py
@@ -82,6 +82,7 @@ from src.market_data import (
detect_source,
get_loader,
)
+from src.factors.research_contract import RESEARCH_STAGES
mcp = FastMCP("Vibe-Trading", version=APP_VERSION)
@@ -962,6 +963,7 @@ def alpha_bench(
top: int = 20,
horizon: int = 1,
output_dir: str | None = None,
+ research_stage: str = "single_factor_evaluation",
) -> str:
"""Benchmark one Alpha Zoo alpha or a complete zoo on a universe.
@@ -976,6 +978,7 @@ def alpha_bench(
non-overlapping (end-anchored); 21 ≈ monthly, the conventional
horizon for fundamental factors. Range 1-252.
output_dir: Optional directory for the generated HTML report.
+ research_stage: Stage recorded in the factor-research contract.
"""
if not alpha_id and not zoo:
return json.dumps(
@@ -1035,6 +1038,15 @@ def alpha_bench(
ensure_ascii=False,
)
+ if research_stage not in RESEARCH_STAGES:
+ return json.dumps(
+ {
+ "status": "error",
+ "error": "MCP alpha_bench research_stage is not supported",
+ },
+ ensure_ascii=False,
+ )
+
params: dict[str, Any] = {
"universe": universe,
"period": period,
@@ -1045,6 +1057,10 @@ def alpha_bench(
params["alpha_id"] = alpha_id
if zoo is not None:
params["zoo"] = zoo
+ # Keep the legacy wire payload byte-for-byte stable when callers use the
+ # default stage; newer clients can opt into the additive research contract.
+ if research_stage != "single_factor_evaluation":
+ params["research_stage"] = research_stage
if output_dir:
from src.config.paths import get_runtime_root
diff --git a/agent/src/factors/bench_runner.py b/agent/src/factors/bench_runner.py
index e9b75b860..e8dec63c3 100644
--- a/agent/src/factors/bench_runner.py
+++ b/agent/src/factors/bench_runner.py
@@ -20,7 +20,7 @@ import math
import os
import time
from concurrent.futures import ProcessPoolExecutor, as_completed
-from typing import Any, Callable, Iterable
+from typing import Any, Callable, Iterable, Mapping
import numpy as np
@@ -38,6 +38,7 @@ from src.factors.registry import (
get_default_registry,
)
from src.factors.data_availability import build_availability_contract
+from src.factors.research_contract import build_bench_research_contract
from src.tools.alpha_bench_tool import _MAX_HORIZON, _compute_forward_returns, _load_universe_panel, _prepare_bench_panel, _split_alphas_by_universe_support, _validate_bench_data_requirements
logger = logging.getLogger(__name__)
@@ -150,6 +151,10 @@ def run_bench(
only: Iterable[str] | None = None,
on_stage: Callable[[str], None] | None = None,
horizon: int = 1,
+ research_mode: str = "explore",
+ research_stage: str = "single_factor_evaluation",
+ research_lineage: Iterable[str | Mapping[str, Any]] | None = None,
+ research_transformations: Iterable[str | Mapping[str, Any]] | None = None,
) -> dict[str, Any]:
"""Run a bench end-to-end and return the API-shaped summary.
@@ -173,6 +178,14 @@ def run_bench(
sampled non-overlapping (end-anchored) so the naive-iid t-stat
stays honest; 21 ≈ monthly, the conventional horizon for
fundamental factors.
+ research_mode: Declared evidence mode for the additive research
+ contract (``explore``, ``strict`` or ``locked``). It is metadata
+ only in this version and does not change the bench math.
+ research_stage: Stage name recorded in the research contract.
+ research_lineage: Optional structured inputs for future artifact
+ lineage. Strings are accepted as a compact form.
+ research_transformations: Optional transformations applied before the
+ bench, such as neutralization or factor combination.
Returns:
Dict with keys: ``status``, ``zoo``, ``universe``, ``period``,
@@ -408,6 +421,18 @@ def run_bench(
period=period,
required_fields=required_fields,
)
+ universe_meta["research"] = build_bench_research_contract(
+ mode=research_mode,
+ stage=research_stage,
+ universe=universe,
+ period=period,
+ factor_ids=alpha_ids,
+ zoo=zoo,
+ lineage=research_lineage,
+ transformations=research_transformations,
+ horizon=horizon,
+ method="rank_ic",
+ )
# Multiple-testing correction. `n_alphas_tested` has always been carried
# here and has only ever been displayed; the best IR out of hundreds of
diff --git a/agent/src/factors/bench_runner_strict.py b/agent/src/factors/bench_runner_strict.py
index 5cfec2d05..e4c03758f 100644
--- a/agent/src/factors/bench_runner_strict.py
+++ b/agent/src/factors/bench_runner_strict.py
@@ -51,7 +51,7 @@ import logging
import math
import time
from dataclasses import dataclass
-from typing import Any, Callable, Literal
+from typing import Any, Callable, Iterable, Literal, Mapping
import numpy as np
import pandas as pd
@@ -64,6 +64,7 @@ from src.factors.registry import (
get_default_registry,
)
from src.factors.data_availability import build_availability_contract
+from src.factors.research_contract import build_bench_research_contract
from src.tools.alpha_bench_tool import _MAX_HORIZON, _compute_forward_returns, _load_universe_panel
logger = logging.getLogger(__name__)
@@ -329,6 +330,10 @@ def run_bench_strict(
horizon: int = 1,
on_progress: ProgressCb | None = None,
registry: Registry | None = None,
+ research_mode: str = "explore",
+ research_stage: str = "single_factor_evaluation",
+ research_lineage: Iterable[str | Mapping[str, Any]] | None = None,
+ research_transformations: Iterable[str | Mapping[str, Any]] | None = None,
) -> dict[str, Any]:
"""Strict-mode bench: like ``run_bench`` but with mandatory random control.
@@ -361,6 +366,13 @@ def run_bench_strict(
fundamental factors.
on_progress: Optional ``(n_done, n_total, alpha_id)`` callback.
registry: Optional pre-built registry for tests.
+ research_mode: Declared evidence mode for the additive research
+ contract. It is metadata only and does not change strict bench
+ statistics.
+ research_stage: Stage name recorded in the research contract.
+ research_lineage: Optional structured inputs for artifact lineage.
+ research_transformations: Optional transformations applied before the
+ bench.
Returns:
Dict containing all the keys ``run_bench()`` returns, plus:
@@ -642,6 +654,19 @@ def run_bench_strict(
period=period,
required_fields=required_fields,
)
+ universe_meta["research"] = build_bench_research_contract(
+ mode=research_mode,
+ stage=research_stage,
+ universe=universe,
+ period=period,
+ factor_ids=alpha_ids,
+ zoo=zoo,
+ lineage=research_lineage,
+ transformations=research_transformations,
+ horizon=horizon,
+ method="paired_random_control" if random_control else "rank_ic",
+ oos_boundary=effective_oos_split,
+ )
# Strip the underscore-prefixed sort helper keys from the wire-bound
# row payloads so they never appear in JSON responses or persisted
diff --git a/agent/src/factors/cli_handlers.py b/agent/src/factors/cli_handlers.py
index 5d080b147..8d6e69a83 100644
--- a/agent/src/factors/cli_handlers.py
+++ b/agent/src/factors/cli_handlers.py
@@ -67,6 +67,7 @@ except Exception: # pragma: no cover — rich is a project dep, fallback only
from src.factors.compare_runner import SORT_KEYS as _COMPARE_SORT_KEYS, compare_alphas
from src.factors.registry import Registry, RegistryError
+from src.factors.research_contract import RESEARCH_STAGES
# Resolve repo root once: this file lives at
@@ -603,11 +604,20 @@ def cmd_alpha_bench(args: argparse.Namespace) -> int:
oos_split=getattr(args, "oos_split", None),
training_cutoff=getattr(args, "training_cutoff", None),
horizon=horizon,
+ research_stage=getattr(
+ args, "research_stage", "single_factor_evaluation"
+ ),
)
else:
from src.factors.bench_runner import run_bench as _run_bench_plain
- run_bench = functools.partial(_run_bench_plain, horizon=horizon)
+ run_bench = functools.partial(
+ _run_bench_plain,
+ horizon=horizon,
+ research_stage=getattr(
+ args, "research_stage", "single_factor_evaluation"
+ ),
+ )
except ImportError as exc:
_err(f"alpha bench failed: bench_runner unavailable ({exc})")
return 1
@@ -1122,6 +1132,12 @@ def add_subparser(subparsers: Any) -> argparse.ArgumentParser:
default=5,
help="Strict mode only: row-shuffled random controls per alpha (default: 5)",
)
+ p_bench.add_argument(
+ "--research-stage",
+ choices=RESEARCH_STAGES,
+ default="single_factor_evaluation",
+ help="Research stage recorded in the factor-research contract",
+ )
p_bench.add_argument(
"--yes",
action="store_true",
diff --git a/agent/src/factors/research_contract.py b/agent/src/factors/research_contract.py
new file mode 100644
index 000000000..a599a4332
--- /dev/null
+++ b/agent/src/factors/research_contract.py
@@ -0,0 +1,185 @@
+"""Structured provenance for factor-research runs.
+
+The factor tools already expose useful metadata, but each entry point used a
+slightly different set of keys. This module defines a small additive contract
+for the research stage, declared mode and factor lineage. It deliberately
+does not run statistics or enforce a policy yet; callers can adopt stricter
+gates without changing the wire shape.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable, Mapping
+from typing import Any
+
+RESEARCH_CONTRACT_SCHEMA = "factor-research.run/v1"
+
+RESEARCH_MODES = ("explore", "strict", "locked")
+RESEARCH_STAGES = (
+ "factor_screening",
+ "single_factor_evaluation",
+ "neutralization",
+ "combination",
+ "composite_evaluation",
+ "backtest",
+ "monitoring",
+)
+
+__all__ = [
+ "RESEARCH_CONTRACT_SCHEMA",
+ "RESEARCH_MODES",
+ "RESEARCH_STAGES",
+ "build_bench_research_contract",
+ "build_research_contract",
+]
+
+
+def _text(value: Any, *, name: str, allow_none: bool = True) -> str | None:
+ if value is None and allow_none:
+ return None
+ if not isinstance(value, str) or not value.strip():
+ raise ValueError(f"{name} must be a non-empty string")
+ return value.strip()
+
+
+def _ids(values: Iterable[str] | None) -> list[str]:
+ result: list[str] = []
+ seen: set[str] = set()
+ for value in values or ():
+ item = _text(value, name="factor id", allow_none=False)
+ assert item is not None
+ if item not in seen:
+ result.append(item)
+ seen.add(item)
+ return result
+
+
+def _records(
+ values: Iterable[str | Mapping[str, Any]] | None,
+ *,
+ name: str,
+) -> list[dict[str, Any]]:
+ records: list[dict[str, Any]] = []
+ for value in values or ():
+ if isinstance(value, str):
+ record = {"id": _text(value, name=f"{name} id", allow_none=False)}
+ elif isinstance(value, Mapping):
+ record = dict(value)
+ else:
+ raise ValueError(f"{name} entries must be strings or mappings")
+ try:
+ json.dumps(record, ensure_ascii=True, allow_nan=False)
+ except (TypeError, ValueError) as exc:
+ raise ValueError(f"{name} entries must be JSON-serializable") from exc
+ records.append(record)
+ return records
+
+
+def _mapping(value: Mapping[str, Any] | None, *, name: str) -> dict[str, Any]:
+ if value is None:
+ return {}
+ if not isinstance(value, Mapping):
+ raise ValueError(f"{name} must be a mapping")
+ result = dict(value)
+ try:
+ json.dumps(result, ensure_ascii=True, allow_nan=False)
+ except (TypeError, ValueError) as exc:
+ raise ValueError(f"{name} must be JSON-serializable") from exc
+ return result
+
+
+def build_research_contract(
+ *,
+ mode: str = "explore",
+ stage: str = "single_factor_evaluation",
+ universe: str | None = None,
+ period: str | None = None,
+ factor_ids: Iterable[str] | None = None,
+ lineage: Iterable[str | Mapping[str, Any]] | None = None,
+ transformations: Iterable[str | Mapping[str, Any]] | None = None,
+ evaluation: Mapping[str, Any] | None = None,
+ locked_test: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+ """Build a JSON-safe, extensible factor-research run summary.
+
+ ``mode`` describes the intended evidence standard for the run. It is
+ metadata in this first contract version; enforcement belongs to a later
+ policy layer so existing callers keep their current behaviour.
+
+ ``lineage`` and ``transformations`` accept either a short string or a
+ structured record. Structured records let future stages add fields such
+ as input artifact hashes, parameters or diagnostics without changing this
+ top-level schema.
+ """
+ mode = _text(mode, name="research mode", allow_none=False)
+ stage = _text(stage, name="research stage", allow_none=False)
+ assert mode is not None and stage is not None
+ if mode not in RESEARCH_MODES:
+ raise ValueError(f"research mode must be one of {RESEARCH_MODES}, got {mode!r}")
+ if stage not in RESEARCH_STAGES:
+ raise ValueError(
+ f"research stage must be one of {RESEARCH_STAGES}, got {stage!r}"
+ )
+
+ universe = _text(universe, name="universe")
+ period = _text(period, name="period")
+ factors = _ids(factor_ids)
+ contract: dict[str, Any] = {
+ "schema": RESEARCH_CONTRACT_SCHEMA,
+ "mode": mode,
+ "stage": stage,
+ "universe": universe,
+ "period": period,
+ "factor_ids": factors,
+ "factor_count": len(factors),
+ "lineage": _records(lineage, name="lineage"),
+ "transformations": _records(transformations, name="transformations"),
+ "evaluation": _mapping(evaluation, name="evaluation"),
+ "locked_test": _mapping(locked_test, name="locked_test"),
+ }
+ json.dumps(contract, ensure_ascii=True, allow_nan=False)
+ return contract
+
+
+def build_bench_research_contract(
+ *,
+ universe: str,
+ period: str,
+ factor_ids: Iterable[str],
+ horizon: int,
+ method: str,
+ zoo: str | None = None,
+ mode: str = "explore",
+ stage: str = "single_factor_evaluation",
+ oos_boundary: str | None = None,
+ lineage: Iterable[str | Mapping[str, Any]] | None = None,
+ transformations: Iterable[str | Mapping[str, Any]] | None = None,
+) -> dict[str, Any]:
+ """Build the shared research summary used by alpha-bench entry points.
+
+ Keeping bench-specific defaults here prevents the CLI, MCP wrapper and
+ both runner implementations from drifting as the contract grows.
+ """
+ evaluation: dict[str, Any] = {
+ "horizon": horizon,
+ "forward_return_sampling": "non_overlapping" if horizon > 1 else "daily",
+ "method": method,
+ }
+ if oos_boundary is not None:
+ evaluation["oos_boundary"] = oos_boundary
+ if lineage is None:
+ source: dict[str, Any] = {"kind": "alpha_registry"}
+ if zoo is not None:
+ source["zoo"] = zoo
+ lineage = [source]
+ return build_research_contract(
+ mode=mode,
+ stage=stage,
+ universe=universe,
+ period=period,
+ factor_ids=factor_ids,
+ lineage=lineage,
+ transformations=transformations,
+ evaluation=evaluation,
+ )
diff --git a/agent/src/skills/factor-research/SKILL.md b/agent/src/skills/factor-research/SKILL.md
index 6e81109ca..1c219d402 100644
--- a/agent/src/skills/factor-research/SKILL.md
+++ b/agent/src/skills/factor-research/SKILL.md
@@ -171,6 +171,11 @@ thresholds using research/training data rather than test-period performance.
See [the neutralization workflow](references/neutralization.md) for
Python and JSON-envelope examples, diagnostics and limits.
+For a shared stage, mode and lineage envelope across alpha bench entry points,
+see [the factor-research run contract](references/research_contract.md).
+The v1 modes are declarative; they do not replace the availability contract or
+enforce locked evaluation by themselves.
+
## Common Pitfalls
### Look-Ahead Bias
diff --git a/agent/src/skills/factor-research/references/research_contract.md b/agent/src/skills/factor-research/references/research_contract.md
new file mode 100644
index 000000000..5cc25146c
--- /dev/null
+++ b/agent/src/skills/factor-research/references/research_contract.md
@@ -0,0 +1,58 @@
+# Factor-research run contract
+
+The factor bench entry points attach an additive `meta.research` object to
+their existing result envelope. The contract is versioned as
+`factor-research.run/v1` and is defined by
+`src.factors.research_contract.build_research_contract`.
+
+```json
+{
+ "schema": "factor-research.run/v1",
+ "mode": "explore",
+ "stage": "single_factor_evaluation",
+ "universe": "csi300",
+ "period": "2020-2025",
+ "factor_ids": ["alpha101_001"],
+ "factor_count": 1,
+ "lineage": [
+ {"kind": "alpha_registry", "zoo": "alpha101"}
+ ],
+ "transformations": [],
+ "evaluation": {
+ "horizon": 1,
+ "forward_return_sampling": "daily",
+ "method": "rank_ic"
+ },
+ "locked_test": {}
+}
+```
+
+## Modes and stages
+
+`mode` records the intended evidence standard:
+
+- `explore`: exploratory research; warnings and incomplete provenance may be
+ acceptable while developing a signal.
+- `strict`: a research result intended for stronger data and statistical
+ review.
+- `locked`: a result intended for a locked evaluation set.
+
+In v1 these values are declarations only. They do not change IC calculations,
+factor weights, or backtest behavior. The public CLI and MCP surfaces expose
+the stage label only; programmatic callers may set a mode for future policy
+experiments. A later policy layer can enforce the modes without changing the
+result schema.
+
+`stage` identifies where the result sits in the factor lifecycle:
+`factor_screening`, `single_factor_evaluation`, `neutralization`,
+`combination`, `composite_evaluation`, `backtest`, or `monitoring`.
+
+## Lineage and transformations
+
+Both `lineage` and `transformations` accept either a short string or a JSON
+object. Use an object when a future stage needs to record artifact IDs,
+parameter hashes, controls, weights, or diagnostic paths. Keep large panels and
+raw data outside the contract; reference them by stable artifact path or hash.
+
+The contract is additive. Existing consumers can ignore `meta.research`, while
+new consumers can use `schema` to opt into the structured fields.
diff --git a/agent/src/tools/alpha_bench_tool.py b/agent/src/tools/alpha_bench_tool.py
index 3d3e36bc3..ab1afecc8 100644
--- a/agent/src/tools/alpha_bench_tool.py
+++ b/agent/src/tools/alpha_bench_tool.py
@@ -47,6 +47,11 @@ from src.agent.tools import BaseTool
from src.config.accessor import get_env_config
from src.config.paths import get_runtime_root
from src.factors.data_availability import build_availability_contract
+from src.factors.research_contract import (
+ RESEARCH_MODES,
+ RESEARCH_STAGES,
+ build_bench_research_contract,
+)
logger = logging.getLogger(__name__)
@@ -1269,6 +1274,19 @@ def run_alpha_bench(**kwargs: Any) -> dict[str, Any]:
if not period or not isinstance(period, str):
return {"status": "error", "error": "period is required (string)"}
+ research_mode = kwargs.get("research_mode", "explore")
+ research_stage = kwargs.get("research_stage", "single_factor_evaluation")
+ if research_mode not in RESEARCH_MODES:
+ return {
+ "status": "error",
+ "error": f"research mode must be one of {RESEARCH_MODES}",
+ }
+ if research_stage not in RESEARCH_STAGES:
+ return {
+ "status": "error",
+ "error": f"research stage must be one of {RESEARCH_STAGES}",
+ }
+
try:
_parse_period(period)
except ValueError as exc:
@@ -1395,6 +1413,19 @@ def run_alpha_bench(**kwargs: Any) -> dict[str, Any]:
period=period,
required_fields=required_fields,
)
+ try:
+ universe_meta["research"] = build_bench_research_contract(
+ mode=research_mode,
+ stage=research_stage,
+ universe=universe,
+ period=period,
+ factor_ids=alpha_ids,
+ zoo=kwargs.get("zoo"),
+ horizon=horizon,
+ method="rank_ic",
+ )
+ except ValueError as exc:
+ return {"status": "error", "error": str(exc)}
context = {
"csp": _CSP,
@@ -1476,6 +1507,12 @@ class AlphaBenchTool(BaseTool):
"conventional horizon for fundamental factors. Range 1-252."
),
},
+ "research_stage": {
+ "type": "string",
+ "enum": list(RESEARCH_STAGES),
+ "default": "single_factor_evaluation",
+ "description": "Stage recorded in the factor-research contract.",
+ },
"output_dir": {
"type": "string",
"description": "Where to write the HTML report; default ~/.vibe-trading/reports/.",
diff --git a/agent/tests/test_research_contract.py b/agent/tests/test_research_contract.py
new file mode 100644
index 000000000..2da1b1f09
--- /dev/null
+++ b/agent/tests/test_research_contract.py
@@ -0,0 +1,55 @@
+"""Tests for the additive factor-research run contract."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from src.factors.research_contract import (
+ RESEARCH_CONTRACT_SCHEMA,
+ build_research_contract,
+)
+
+
+def test_contract_is_json_safe_and_preserves_stage_lineage() -> None:
+ contract = build_research_contract(
+ mode="strict",
+ stage="composite_evaluation",
+ universe="csi300",
+ period="2020-2025",
+ factor_ids=["value", "value", "momentum"],
+ lineage=["value_raw", {"kind": "neutralized", "id": "momentum_neutralized"}],
+ transformations=[
+ {"kind": "neutralization", "controls": ["industry", "size"]},
+ "walk_forward_combination",
+ ],
+ evaluation={"horizon": 21, "method": "icir"},
+ )
+
+ assert contract["schema"] == RESEARCH_CONTRACT_SCHEMA
+ assert contract["mode"] == "strict"
+ assert contract["stage"] == "composite_evaluation"
+ assert contract["factor_ids"] == ["value", "momentum"]
+ assert contract["factor_count"] == 2
+ assert contract["lineage"][0] == {"id": "value_raw"}
+ assert contract["transformations"][1] == {"id": "walk_forward_combination"}
+ json.dumps(contract, ensure_ascii=True, allow_nan=False)
+
+
+ ("field", "value"),
+ [
+ ("mode", "audit"),
+ ("stage", "unknown_stage"),
+ ],
+)
+def test_contract_rejects_unknown_enums(field: str, value: str) -> None:
+ kwargs = {field: value}
+ with pytest.raises(ValueError, match=field):
+ build_research_contract(**kwargs)
+
+
+def test_contract_rejects_non_json_extension_records() -> None:
+ with pytest.raises(ValueError, match="lineage"):
+ build_research_contract(lineage=[{"hash": object()}])
diff --git a/agent/tests/test_research_contract_integration.py b/agent/tests/test_research_contract_integration.py
new file mode 100644
index 000000000..7ff54f037
--- /dev/null
+++ b/agent/tests/test_research_contract_integration.py
@@ -0,0 +1,144 @@
+"""Entry-point coverage for the factor-research run contract.
+
+These tests exercise both bench runners with an injected in-memory registry and
+panel. They verify the contract survives the runner's public result envelope
+without making network requests or depending on the bundled alpha catalogue.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+import pandas as pd
+import pytest
+
+from src.factors.bench_runner import run_bench
+from src.factors.bench_runner_strict import run_bench_strict
+
+
+def _panel(n_rows: int = 48, n_symbols: int = 6) -> dict[str, Any]:
+ rng = np.random.default_rng(2026)
+ index = pd.date_range("2024-01-01", periods=n_rows, freq="D")
+ symbols = [f"S{i}" for i in range(n_symbols)]
+ close = pd.DataFrame(
+ 100.0 + np.cumsum(rng.normal(size=(n_rows, n_symbols)), axis=0),
+ index=index,
+ columns=symbols,
+ )
+ return {
+ "close": close,
+ "open": close,
+ "high": close * 1.01,
+ "low": close * 0.99,
+ "volume": pd.DataFrame(1_000_000.0, index=index, columns=symbols),
+ "_meta": {"source": "test-panel"},
+ }
+
+
+class _Registry:
+ """Small registry slice consumed by both bench runners."""
+
+ ids = ["alpha_a", "alpha_b"]
+
+ def list(self, *, zoo: str) -> list[str]: # noqa: ARG002
+ return list(self.ids)
+
+ def get(self, alpha_id: str) -> Any:
+ class _Handle:
+ meta = {
+ "theme": ["test"],
+ "formula_latex": "close",
+ "columns_required": [],
+ }
+
+ _Handle.alpha_id = alpha_id
+ return _Handle()
+
+ def compute(self, alpha_id: str, panel: dict[str, Any]) -> pd.DataFrame:
+ close = panel["close"]
+ if alpha_id == "alpha_a":
+ return close
+ # Keep the second factor distinct while retaining a fully populated
+ # cross-section for Spearman IC calculations.
+ return close.rank(axis=1, method="first")
+
+
+def _patch_plain_runner(monkeypatch: pytest.MonkeyPatch) -> None:
+ panel = _panel()
+ monkeypatch.setattr(
+ "src.factors.bench_runner._load_universe_panel",
+ lambda universe, period: panel, # noqa: ARG005
+ )
+ monkeypatch.setattr(
+ "src.factors.bench_runner._compute_forward_returns",
+ lambda panel_in, horizon=1: panel_in["close"].pct_change(fill_method=None).shift(-1),
+ )
+
+
+def _patch_strict_runner(monkeypatch: pytest.MonkeyPatch) -> None:
+ panel = _panel()
+ monkeypatch.setattr(
+ "src.factors.bench_runner_strict._load_universe_panel",
+ lambda universe, period: panel, # noqa: ARG005
+ )
+ monkeypatch.setattr(
+ "src.factors.bench_runner_strict._compute_forward_returns",
+ lambda panel_in, horizon=1: panel_in["close"].pct_change(fill_method=None).shift(-1),
+ )
+
+
+def test_plain_runner_emits_research_contract(monkeypatch: pytest.MonkeyPatch) -> None:
+ _patch_plain_runner(monkeypatch)
+
+ result = run_bench(
+ "test_zoo",
+ "mock",
+ "2024-2024",
+ registry=_Registry(),
+ research_stage="neutralization",
+ research_lineage=["raw_alpha_library"],
+ research_transformations=[{"kind": "neutralization", "controls": ["size"]}],
+ horizon=21,
+ )
+
+ assert result["status"] == "ok"
+ research = result["meta"]["research"]
+ assert research["schema"] == "factor-research.run/v1"
+ assert research["stage"] == "neutralization"
+ assert research["factor_ids"] == ["alpha_a", "alpha_b"]
+ assert research["factor_count"] == 2
+ assert research["lineage"] == [{"id": "raw_alpha_library"}]
+ assert research["transformations"] == [
+ {"kind": "neutralization", "controls": ["size"]}
+ ]
+ assert research["evaluation"] == {
+ "horizon": 21,
+ "forward_return_sampling": "non_overlapping",
+ "method": "rank_ic",
+ }
+
+
+def test_strict_runner_emits_research_contract(monkeypatch: pytest.MonkeyPatch) -> None:
+ _patch_strict_runner(monkeypatch)
+
+ result = run_bench_strict(
+ "test_zoo",
+ "mock",
+ "2024-2024",
+ random_control=False,
+ registry=_Registry(),
+ research_stage="composite_evaluation",
+ research_lineage=[{"kind": "combined_factor", "id": "combo_1"}],
+ research_transformations=["walk_forward_combination"],
+ )
+
+ assert result["status"] == "ok"
+ research = result["meta"]["research"]
+ assert research["schema"] == "factor-research.run/v1"
+ assert research["stage"] == "composite_evaluation"
+ assert research["factor_ids"] == ["alpha_a", "alpha_b"]
+ assert research["evaluation"]["method"] == "rank_ic"
+ assert research["evaluation"]["horizon"] == 1
+ assert research["lineage"] == [{"kind": "combined_factor", "id": "combo_1"}]
+ assert research["transformations"] == [{"id": "walk_forward_combination"}]