Skip to content

"Vibe-Trading: Your Personal Trading Agent"

feat(alpha-bench): add field-level data availability contract

BH Hu09605ea4dd9a
diff --git a/README.md b/README.md
index af43cfd93..c9a646369 100644
--- a/README.md
+++ b/README.md
@@ -1528,6 +1528,15 @@ incompatible with `position_adjustment="hold"`.
vibe-trading alpha bench --zoo gtja191 --universe csi300 --period 2018-2025 --top 20
```
+Bench results also carry `meta.data_availability`, a field-level contract for
+the loaded inputs. It records the market adapter, venue, currency, calendar,
+observed window, serving source, validation coverage, and an explicit status:
+`verified`, `assumed`, `unknown`, or `failed`. Date-only fundamental filings
+remain `unknown` when the source does not expose a publication timestamp, even
+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.
+
**Browse the catalogue** and inspect a single alpha:
```bash
vibe-trading alpha list --zoo gtja191 --theme reversal --limit 10
diff --git a/agent/src/factors/bench_runner.py b/agent/src/factors/bench_runner.py
index ad1134107..e9b75b860 100644
--- a/agent/src/factors/bench_runner.py
+++ b/agent/src/factors/bench_runner.py
@@ -37,6 +37,7 @@ from src.factors.registry import (
SkipAlpha,
get_default_registry,
)
+from src.factors.data_availability import build_availability_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__)
@@ -394,6 +395,20 @@ def run_bench(
except Exception: # noqa: BLE001
universe_meta = {"raw": str(universe_meta_raw)}
+ required_fields = sorted(
+ {
+ str(column)
+ for aid in alpha_ids
+ for column in (reg.get(aid).meta or {}).get("columns_required", [])
+ }
+ )
+ universe_meta["data_availability"] = build_availability_contract(
+ panel,
+ universe=universe,
+ period=period,
+ required_fields=required_fields,
+ )
+
# Multiple-testing correction. `n_alphas_tested` has always been carried
# here and has only ever been displayed; the best IR out of hundreds of
# searched alphas is the maximum of hundreds of draws, and under a null
diff --git a/agent/src/factors/bench_runner_strict.py b/agent/src/factors/bench_runner_strict.py
index 0bd31ddd1..5cfec2d05 100644
--- a/agent/src/factors/bench_runner_strict.py
+++ b/agent/src/factors/bench_runner_strict.py
@@ -63,6 +63,7 @@ from src.factors.registry import (
SkipAlpha,
get_default_registry,
)
+from src.factors.data_availability import build_availability_contract
from src.tools.alpha_bench_tool import _MAX_HORIZON, _compute_forward_returns, _load_universe_panel
logger = logging.getLogger(__name__)
@@ -628,6 +629,20 @@ def run_bench_strict(
except Exception: # noqa: BLE001
universe_meta = {"raw": str(universe_meta_raw)}
+ required_fields = sorted(
+ {
+ str(column)
+ for aid in alpha_ids
+ for column in (reg.get(aid).meta or {}).get("columns_required", [])
+ }
+ )
+ universe_meta["data_availability"] = build_availability_contract(
+ panel,
+ universe=universe,
+ period=period,
+ required_fields=required_fields,
+ )
+
# Strip the underscore-prefixed sort helper keys from the wire-bound
# row payloads so they never appear in JSON responses or persisted
# results. Keep the rest of the row schema as-is so dashboards see
diff --git a/agent/src/factors/data_availability.py b/agent/src/factors/data_availability.py
new file mode 100644
index 000000000..75e39a6dc
--- /dev/null
+++ b/agent/src/factors/data_availability.py
@@ -0,0 +1,321 @@
+"""Field-level data availability contracts for alpha benchmarks.
+
+The benchmark already exposes universe and run metadata. This module adds a
+small, extensible description of when each input can be known. It deliberately
+does not replace ``RunManifest`` or ``run_card.json``; callers attach the
+returned contract to their existing ``meta`` payload.
+
+Adapters provide market identity and field semantics. A future market can
+register an adapter without changing the bench runner or the wire schema.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Iterable, Mapping, Protocol
+
+
+AVAILABILITY_SCHEMA = "alpha-bench.data-availability/v1"
+VALID_STATUSES = frozenset({"verified", "assumed", "unknown", "failed"})
+_PRICE_FIELDS = frozenset({"open", "high", "low", "close", "volume", "amount", "vwap"})
+
+
+@dataclass(frozen=True)
+class MarketContext:
+ """Stable identity fields shared by all records in one bench."""
+
+ asset_class: str
+ venue: str
+ currency: str
+ timezone: str
+ calendar: str
+
+
+class AvailabilityAdapter(Protocol):
+ """Extension point for a market-specific availability policy."""
+
+ name: str
+
+ def context(self, universe: str, metadata: Mapping[str, Any]) -> MarketContext:
+ """Return market identity for a panel and its loader metadata."""
+
+ def field_policy(self, field: str, metadata: Mapping[str, Any]) -> Mapping[str, Any]:
+ """Return semantics such as ``kind`` and ``availability_mode``."""
+
+
+@dataclass(frozen=True)
+class _BuiltinAdapter:
+ name: str
+ market: MarketContext
+
+ def context(self, universe: str, metadata: Mapping[str, Any]) -> MarketContext:
+ del universe, metadata
+ return self.market
+
+ def field_policy(self, field: str, metadata: Mapping[str, Any]) -> Mapping[str, Any]:
+ del metadata
+ if field == "universe:membership":
+ return {"kind": "membership", "availability_mode": "effective_date"}
+ if field.startswith("fund:"):
+ return {"kind": "event", "availability_mode": "filing_date"}
+ if field.startswith("val:"):
+ return {"kind": "market", "availability_mode": "session_date"}
+ if field == "sector":
+ return {"kind": "classification", "availability_mode": "effective_date"}
+ if field in _PRICE_FIELDS:
+ return {"kind": "bar", "availability_mode": "bar_close"}
+ return {"kind": "unknown", "availability_mode": "unknown"}
+
+
+_ADAPTERS: dict[str, AvailabilityAdapter] = {
+ "csi300": _BuiltinAdapter(
+ "cn_equity",
+ MarketContext("equity", "XSHG+XSHE", "CNY", "Asia/Shanghai", "SSE/SZSE"),
+ ),
+ "sp500": _BuiltinAdapter(
+ "us_equity",
+ MarketContext("equity", "XNYS+XNAS", "USD", "America/New_York", "NYSE/NASDAQ"),
+ ),
+ "btc-usdt": _BuiltinAdapter(
+ "crypto",
+ MarketContext("crypto", "global", "USDT", "UTC", "24/7"),
+ ),
+}
+_GENERIC_ADAPTER = _BuiltinAdapter(
+ "generic",
+ MarketContext("unknown", "unknown", "unknown", "UTC", "unknown"),
+)
+
+
+def register_availability_adapter(universe: str, adapter: AvailabilityAdapter) -> None:
+ """Register or replace the adapter used for one universe key.
+
+ Adapters are process-local and intentionally do not alter the benchmark
+ registry. Applications that add a new market can register one at startup,
+ while the persisted contract remains schema-compatible.
+ """
+ key = str(universe).strip().lower()
+ if not key:
+ raise ValueError("universe must be a non-empty string")
+ if not getattr(adapter, "name", None):
+ raise ValueError("availability adapter must expose a non-empty name")
+ _ADAPTERS[key] = adapter
+
+
+def _metadata(panel: Mapping[str, Any]) -> dict[str, Any]:
+ raw = panel.get("_meta")
+ if raw is None:
+ return {}
+ if isinstance(raw, Mapping):
+ return dict(raw)
+ try:
+ return dict(raw.to_dict())
+ except Exception: # noqa: BLE001 - metadata must never break a bench
+ return {"raw": str(raw)}
+
+
+def _date_text(value: Any) -> str | None:
+ if value is None:
+ return None
+ try:
+ return value.date().isoformat()
+ except AttributeError:
+ text = str(value)
+ return text[:10] if text else None
+
+
+def _json_text(value: Any) -> Any:
+ """Keep timestamps and date-like values JSON-safe without losing precision."""
+ if value is None or isinstance(value, (str, int, float, bool)):
+ return value
+ isoformat = getattr(value, "isoformat", None)
+ if callable(isoformat):
+ return isoformat()
+ return str(value)
+
+
+def _panel_window(panel: Mapping[str, Any]) -> dict[str, str | None]:
+ starts: list[Any] = []
+ ends: list[Any] = []
+ for value in panel.values():
+ index = getattr(value, "index", None)
+ if index is None or len(index) == 0:
+ continue
+ starts.append(index[0])
+ ends.append(index[-1])
+ return {
+ "start": _date_text(min(starts)) if starts else None,
+ "end": _date_text(max(ends)) if ends else None,
+ }
+
+def _validation(value: Any) -> dict[str, Any]:
+ if not hasattr(value, "notna") or not hasattr(value, "shape"):
+ return {"present": value is not None}
+ rows, columns = value.shape[:2]
+ cells = rows * columns
+ if cells == 0:
+ return {"present": False, "rows": rows, "symbols": columns, "non_null_ratio": 0.0}
+ try:
+ non_null = int(value.notna().to_numpy().sum())
+ except (AttributeError, TypeError, ValueError):
+ return {"present": True, "rows": rows, "symbols": columns}
+ return {
+ "present": True,
+ "rows": rows,
+ "symbols": columns,
+ "non_null_ratio": round(non_null / cells, 6),
+ }
+
+
+def _source_for(field: str, metadata: Mapping[str, Any], universe: str) -> str | None:
+ field_sources = metadata.get("field_sources")
+ if isinstance(field_sources, Mapping) and field_sources.get(field):
+ return str(field_sources[field])
+ if field == "universe:membership":
+ return str(metadata["constituent_source"]) if metadata.get("constituent_source") else None
+ if field == "sector":
+ return str(metadata["sector_source"]) if metadata.get("sector_source") else None
+ if field.startswith("fund:"):
+ return str(metadata["fundamental_source"]) if metadata.get("fundamental_source") else None
+ if field.startswith("val:"):
+ return str(metadata["valuation_source"]) if metadata.get("valuation_source") else None
+ price_sources = metadata.get("price_sources")
+ if isinstance(price_sources, (list, tuple, set)) and price_sources:
+ return ",".join(sorted(str(item) for item in price_sources))
+ if universe == "csi300":
+ return "tushare"
+ if universe == "btc-usdt":
+ return str(metadata["price_source"]) if metadata.get("price_source") else None
+ return None
+
+
+def _field_status(
+ field: str,
+ *,
+ present: bool,
+ source: str | None,
+ policy: Mapping[str, Any],
+ field_metadata: Mapping[str, Any],
+ metadata: Mapping[str, Any],
+ required: bool,
+) -> tuple[str, bool, str | None]:
+ explicit = field_metadata.get("status")
+ if explicit in VALID_STATUSES:
+ status = str(explicit)
+ elif not present:
+ status = "failed" if required else "unknown"
+ elif field_metadata.get("available_at") or field_metadata.get("availability_timestamp"):
+ status = "verified"
+ elif policy.get("kind") == "membership":
+ status = "verified" if metadata.get("pit_membership") is True else "unknown"
+ elif field.startswith("fund:"):
+ # A one-bar shift is useful protection, but date-only filings do not
+ # prove the exact publication time. Keep this explicitly non-PIT-safe.
+ status = "unknown"
+ elif source:
+ status = "assumed"
+ else:
+ status = "unknown"
+
+ pit_safe = bool(field_metadata.get("pit_safe", status == "verified"))
+ if status != "verified":
+ pit_safe = False
+ reason = field_metadata.get("reason")
+ if reason is None and status == "unknown" and field.startswith("fund:"):
+ reason = "source exposes a filing date but no precise publication timestamp"
+ return status, pit_safe, str(reason) if reason is not None else None
+
+
+def build_availability_contract(
+ panel: Mapping[str, Any],
+ *,
+ universe: str,
+ period: str | None = None,
+ required_fields: Iterable[str] | None = None,
+) -> dict[str, Any]:
+ """Build a JSON-safe field-level availability contract for a bench panel.
+
+ ``required_fields`` may include declared alpha inputs that were absent from
+ the loaded panel. Those records receive ``failed`` and make missing inputs
+ visible without changing factor calculations.
+ """
+ universe_key = str(universe).strip().lower()
+ metadata = _metadata(panel)
+ adapter = _ADAPTERS.get(universe_key, _GENERIC_ADAPTER)
+ context = adapter.context(universe_key, metadata)
+ required = {str(field) for field in (required_fields or ())}
+ observed = {str(field) for field in panel if not str(field).startswith("_")}
+ if metadata.get("pit_membership") is not None or metadata.get("survivorship_bias") is not None:
+ observed.add("universe:membership")
+ fields = sorted(observed | required)
+ window = _panel_window(panel)
+ contract_fields: list[dict[str, Any]] = []
+ field_availability = metadata.get("field_availability")
+ if not isinstance(field_availability, Mapping):
+ field_availability = {}
+
+ for field in fields:
+ value = panel.get(field)
+ present = field == "universe:membership" or value is not None
+ field_metadata = field_availability.get(field, {})
+ if not isinstance(field_metadata, Mapping):
+ field_metadata = {}
+ policy = adapter.field_policy(field, metadata)
+ source = _source_for(field, metadata, universe_key)
+ fingerprint = field_metadata.get("fingerprint")
+ field_fingerprints = metadata.get("field_fingerprints")
+ if not fingerprint and isinstance(field_fingerprints, Mapping):
+ fingerprint = field_fingerprints.get(field)
+ status, pit_safe, reason = _field_status(
+ field,
+ present=present,
+ source=source,
+ policy=policy,
+ field_metadata=field_metadata,
+ metadata=metadata,
+ required=field in required,
+ )
+ record: dict[str, Any] = {
+ "field": field,
+ "source": source,
+ "observation_date": _json_text(field_metadata.get("observation_date")),
+ "observation_window": dict(window),
+ "availability_mode": _json_text(
+ field_metadata.get("availability_mode", policy.get("availability_mode", "unknown"))
+ ),
+ "available_at": _json_text(
+ field_metadata.get("available_at")
+ or field_metadata.get("availability_timestamp")
+ ),
+ "fingerprint": _json_text(fingerprint),
+ "status": status,
+ "pit_safe": pit_safe,
+ "validation": _validation(value) if field != "universe:membership" else {
+ "present": True,
+ "pit_membership": metadata.get("pit_membership"),
+ "survivorship_bias": metadata.get("survivorship_bias"),
+ },
+ }
+ if reason:
+ record["reason"] = reason
+ if field_metadata.get("effective_from") is not None:
+ record["effective_from"] = _json_text(field_metadata["effective_from"])
+ contract_fields.append(record)
+
+ warnings: list[str] = []
+ if metadata.get("survivorship_bias"):
+ warnings.append("universe membership is not point-in-time and may be survivorship-biased")
+ if any(item["status"] == "unknown" for item in contract_fields):
+ warnings.append("one or more fields lack a verified availability timestamp")
+ return {
+ "schema": AVAILABILITY_SCHEMA,
+ "adapter": adapter.name,
+ "asset_class": context.asset_class,
+ "venue": context.venue,
+ "currency": context.currency,
+ "timezone": context.timezone,
+ "calendar": context.calendar,
+ "period": {"requested": period, **window},
+ "fields": contract_fields,
+ "warnings": warnings,
+ }
diff --git a/agent/src/tools/alpha_bench_tool.py b/agent/src/tools/alpha_bench_tool.py
index c4bee497d..3d3e36bc3 100644
--- a/agent/src/tools/alpha_bench_tool.py
+++ b/agent/src/tools/alpha_bench_tool.py
@@ -46,6 +46,7 @@ from backtest.loaders.cn_adjust import apply_qfq as _apply_qfq
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
logger = logging.getLogger(__name__)
@@ -625,6 +626,10 @@ def _load_btc_panel(start: str, end: str) -> dict[str, pd.DataFrame]:
panel = _wide_from_fetched(fetched, include_amount=False)
if all(k in panel for k in ("open", "high", "low", "close")):
panel["vwap"] = (panel["open"] + panel["high"] + panel["low"] + panel["close"]) / 4.0
+ panel["_meta"] = {
+ "universe": "btc-usdt",
+ "price_source": getattr(loader, "name", None) or "crypto",
+ }
return panel
@@ -1375,6 +1380,22 @@ def run_alpha_bench(**kwargs: Any) -> dict[str, Any]:
ts = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
report_path = output_dir / f"alpha_bench_{ts}_{secrets.token_hex(16)}.html"
+ required_fields = sorted(
+ {
+ str(column)
+ for aid in alpha_ids
+ for column in (registry.get(aid).meta or {}).get("columns_required", [])
+ }
+ )
+ panel_meta = panel.get("_meta") if isinstance(panel, dict) else None
+ universe_meta = dict(panel_meta) if isinstance(panel_meta, dict) else {}
+ universe_meta["data_availability"] = build_availability_contract(
+ panel,
+ universe=universe,
+ period=period,
+ required_fields=required_fields,
+ )
+
context = {
"csp": _CSP,
"css": _REPORT_CSS,
@@ -1385,6 +1406,7 @@ def run_alpha_bench(**kwargs: Any) -> dict[str, Any]:
"n_skipped": len(failures),
"top": top,
"failures": failures[:10],
+ "meta": universe_meta,
}
try:
@@ -1404,6 +1426,7 @@ def run_alpha_bench(**kwargs: Any) -> dict[str, Any]:
"horizon": horizon,
"forward_return_sampling": "non_overlapping" if horizon > 1 else "daily",
"top": top,
+ "meta": universe_meta,
}
if universe_excluded:
envelope["universe_excluded"] = universe_excluded
diff --git a/agent/tests/test_data_availability.py b/agent/tests/test_data_availability.py
new file mode 100644
index 000000000..0d10e4c48
--- /dev/null
+++ b/agent/tests/test_data_availability.py
@@ -0,0 +1,130 @@
+"""Offline tests for the alpha-bench field availability contract."""
+
+from __future__ import annotations
+
+import json
+
+import pandas as pd
+
+from src.factors.data_availability import (
+ MarketContext,
+ build_availability_contract,
+ register_availability_adapter,
+)
+
+
+def _panel() -> dict:
+ index = pd.date_range("2026-01-02", periods=2, freq="D")
+ return {
+ "close": pd.DataFrame({"600519.SH": [10.0, 10.2]}, index=index),
+ "fund:revenue": pd.DataFrame({"600519.SH": [100.0, 100.0]}, index=index),
+ "_meta": {
+ "pit_membership": True,
+ "survivorship_bias": False,
+ "constituent_source": "tushare index_weight",
+ "fundamental_source": "sec",
+ },
+ }
+
+
+def _fields(contract: dict) -> dict[str, dict]:
+ return {item["field"]: item for item in contract["fields"]}
+
+
+def test_contract_distinguishes_verified_assumed_unknown_and_failed() -> None:
+ contract = build_availability_contract(
+ _panel(),
+ universe="csi300",
+ period="2026-01-01/2026-01-31",
+ required_fields=["fund:revenue", "fund:eps"],
+ )
+
+ fields = _fields(contract)
+ assert contract["schema"] == "alpha-bench.data-availability/v1"
+ assert contract["asset_class"] == "equity"
+ assert contract["venue"] == "XSHG+XSHE"
+ assert fields["universe:membership"]["status"] == "verified"
+ assert fields["universe:membership"]["source"] == "tushare index_weight"
+ assert fields["universe:membership"]["pit_safe"] is True
+ assert fields["close"]["status"] == "assumed"
+ assert fields["close"]["pit_safe"] is False
+ assert fields["fund:revenue"]["status"] == "unknown"
+ assert fields["fund:revenue"]["pit_safe"] is False
+ assert "timestamp" in fields["fund:revenue"]["reason"]
+ assert fields["fund:eps"]["status"] == "failed"
+ assert fields["fund:eps"]["validation"]["present"] is False
+ assert any("timestamp" in warning for warning in contract["warnings"])
+ json.dumps(contract)
+
+
+def test_exact_field_timestamp_can_be_verified() -> None:
+ panel = {
+ "close": pd.DataFrame(
+ {"AAPL.US": [100.0]}, index=pd.DatetimeIndex(["2026-01-02"])
+ ),
+ "fund:revenue": pd.DataFrame(
+ {"AAPL.US": [10.0]}, index=pd.DatetimeIndex(["2026-01-02"])
+ ),
+ "_meta": {
+ "price_sources": ["yfinance"],
+ "fundamental_source": "sec",
+ "field_fingerprints": {"close": "sha256:bars"},
+ "field_availability": {
+ "close": {
+ "observation_date": "2026-01-02",
+ "available_at": "2026-01-02T21:00:00Z",
+ "pit_safe": True,
+ },
+ "fund:revenue": {
+ "available_at": "2026-01-02T16:00:00Z",
+ "pit_safe": True,
+ },
+ },
+ },
+ }
+
+ close = _fields(build_availability_contract(panel, universe="sp500"))["close"]
+ assert close["status"] == "verified"
+ assert close["pit_safe"] is True
+ assert close["observation_date"] == "2026-01-02"
+ assert close["available_at"] == "2026-01-02T21:00:00Z"
+ assert close["fingerprint"] == "sha256:bars"
+ assert _fields(build_availability_contract(panel, universe="sp500"))["fund:revenue"]["status"] == "verified"
+
+
+def test_future_market_can_register_an_adapter_without_runner_changes() -> None:
+ class _FutureAdapter:
+ name = "future_market"
+
+ def context(self, universe, metadata):
+ del universe, metadata
+ return MarketContext("future", "XNEW", "USD", "UTC", "XNEW")
+
+ def field_policy(self, field, metadata):
+ del field, metadata
+ return {"kind": "bar", "availability_mode": "bar_close"}
+
+ register_availability_adapter("future-market", _FutureAdapter())
+ panel = {
+ "close": pd.DataFrame(
+ {"NEW1": [1.0]}, index=pd.DatetimeIndex(["2026-01-02"])
+ ),
+ "_meta": {"price_sources": ["new-feed"]},
+ }
+
+ contract = build_availability_contract(panel, universe="future-market")
+ assert contract["adapter"] == "future_market"
+ assert contract["asset_class"] == "future"
+ assert _fields(contract)["close"]["source"] == "new-feed"
+
+
+def test_metadata_without_source_is_explicitly_unknown() -> None:
+ panel = {
+ "close": pd.DataFrame(
+ {"X": [1.0]}, index=pd.DatetimeIndex(["2026-01-02"])
+ )
+ }
+ close = _fields(build_availability_contract(panel, universe="unregistered"))["close"]
+ assert close["status"] == "unknown"
+ assert close["source"] is None
+ assert close["pit_safe"] is False