"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
feat(alpha-bench): add field-level data availability contract
BH Hu09605ea4dd9a
diff --git a/README.md b/README.mdindex 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:```bashvibe-trading alpha list --zoo gtja191 --theme reversal --limit 10diff --git a/agent/src/factors/bench_runner.py b/agent/src/factors/bench_runner.pyindex 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_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__)@@ -394,6 +395,20 @@ def run_bench(except Exception: # noqa: BLE001universe_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 nulldiff --git a/agent/src/factors/bench_runner_strict.py b/agent/src/factors/bench_runner_strict.pyindex 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_contractfrom src.tools.alpha_bench_tool import _MAX_HORIZON, _compute_forward_returns, _load_universe_panellogger = logging.getLogger(__name__)@@ -628,6 +629,20 @@ def run_bench_strict(except Exception: # noqa: BLE001universe_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 seediff --git a/agent/src/factors/data_availability.py b/agent/src/factors/data_availability.pynew file mode 100644index 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.pyindex 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_qfqfrom src.agent.tools import BaseToolfrom src.config.accessor import get_env_configfrom src.config.paths import get_runtime_root+from src.factors.data_availability import build_availability_contractlogger = 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_excludeddiff --git a/agent/tests/test_data_availability.py b/agent/tests/test_data_availability.pynew file mode 100644index 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