"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
feat(factors): add research provenance contract
BHhhh-123cb803f9eb681
diff --git a/README.md b/README.mdindex 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 treatthem as PIT-safe. New markets can register an adapter without changing thiswire 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:```bashvibe-trading alpha list --zoo gtja191 --theme reversal --limit 10diff --git a/agent/mcp_server.py b/agent/mcp_server.pyindex 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_STAGESmcp = 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 conventionalhorizon 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_idif 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_stageif output_dir:from src.config.paths import get_runtime_rootdiff --git a/agent/src/factors/bench_runner.py b/agent/src/factors/bench_runner.pyindex e9b75b860..e8dec63c3 100644--- a/agent/src/factors/bench_runner.py+++ b/agent/src/factors/bench_runner.py@@ -20,7 +20,7 @@ import mathimport osimport timefrom concurrent.futures import ProcessPoolExecutor, as_completed-from typing import Any, Callable, Iterable+from typing import Any, Callable, Iterable, Mappingimport 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_contractfrom 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_requirementslogger = 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-statstays honest; 21 ≈ monthly, the conventional horizon forfundamental 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 ofdiff --git a/agent/src/factors/bench_runner_strict.py b/agent/src/factors/bench_runner_strict.pyindex 5cfec2d05..e4c03758f 100644--- a/agent/src/factors/bench_runner_strict.py+++ b/agent/src/factors/bench_runner_strict.py@@ -51,7 +51,7 @@ import loggingimport mathimport timefrom dataclasses import dataclass-from typing import Any, Callable, Literal+from typing import Any, Callable, Iterable, Literal, Mappingimport numpy as npimport 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_contractfrom src.tools.alpha_bench_tool import _MAX_HORIZON, _compute_forward_returns, _load_universe_panellogger = 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 persisteddiff --git a/agent/src/factors/cli_handlers.py b/agent/src/factors/cli_handlers.pyindex 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 onlyfrom src.factors.compare_runner import SORT_KEYS as _COMPARE_SORT_KEYS, compare_alphasfrom 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.pynew file mode 100644index 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.mdindex 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) forPython 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 Biasdiff --git a/agent/src/skills/factor-research/references/research_contract.md b/agent/src/skills/factor-research/references/research_contract.mdnew file mode 100644index 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.pyindex 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 BaseToolfrom src.config.accessor import get_env_configfrom src.config.paths import get_runtime_rootfrom 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.pynew file mode 100644index 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.pynew file mode 100644index 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"}]