"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
"""Evidence-gated facade over Alpha Zoo and the SDM strategy store.
``StrategyDiscoveryFacade`` unifies the two strategy surfaces (Alpha Zoo
registry + Strategy Development Manager store) behind one read-only catalog
and answers per-regime questions **only from harness-computed evidence**. It
never invents performance numbers: when the evidence table is empty it says
so, and when a dependency degrades (registry failed to load, store
unreachable) it logs a warning and returns an honest partial result instead
of raising.
Heavy dependencies (``src.factors.registry``, ``src.strategy_store``) are
imported lazily inside methods — module import stays cheap and tests can
inject fakes through the constructor.
"""
from __future__ import annotations
import dataclasses
import logging
import math
from datetime import date
from typing import Any
from src.strategy_discovery.evidence_store import EvidenceStore
from src.strategy_discovery.models import (
BORDERLINE_BREAKEVEN_BPS,
BORDERLINE_COVERAGE_BUFFER_DAYS,
BORDERLINE_TRADE_BUFFER,
DECAY_STALE,
MIN_COVERAGE_DAYS,
MIN_TRADES,
QUALITY_ORDER,
REGIMES,
StrategySummary,
classify_decay,
coverage_days_from_ranges,
decay_warning,
evidence_age_days,
staleness_days,
)
logger = logging.getLogger(__name__)
_VALID_SOURCES = ("alpha_zoo", "sdm")
#: Upper bound used when draining the SDM artifact list for catalog display.
_SDM_SCAN_LIMIT = 100_000
#: Extra warning appended to rows that pass every filter but sit inside the
#: #969 adversarial buffer bands. Verbatim contract text — tools match it.
_BORDERLINE_WARNING = (
"borderline-evidence: just inside one or more thresholds — "
"cite the raw figures, not the verdict"
)
#: Note attached to query results when the evidence table is completely empty.
#: Names the population path: the ``refresh_strategy_evidence`` tool (agent +
#: MCP) and the ``vibe-trading strategy-evidence refresh`` CLI command, both
#: of which drive the evidence harness over reproducible run artifacts.
_EMPTY_EVIDENCE_NOTE = (
"No per-regime evidence computed yet. Populate the store with "
"`refresh_strategy_evidence` — exposed as an agent/MCP tool and as the "
"CLI command `vibe-trading strategy-evidence refresh --manifest <path>` — "
"which rebuilds evidence from reproducible backtest run artifacts "
"(library callers may drive "
"src.strategy_discovery.evidence_harness.rebuild_evidence directly). The "
"facade refuses to assess regimes without evidence."
)
#: SDM lifecycle states that exclude an ``sdm:*`` row from default
#: recommendations regardless of evidence freshness (plan D8 lifecycle
#: mirroring — artifact status only, never the DecayEvaluator FSM).
_SDM_EXCLUDED_STATUSES = ("decayed", "disabled")
#: Stable prefix for lifecycle exclusions surfaced on inspection rows.
_SDM_LIFECYCLE_PREFIX = "sdm-lifecycle:"
def _error(message: str) -> dict[str, Any]:
"""Standard error envelope shared with the other agent tool modules."""
return {"status": "error", "error": message}
def _json_safe(value: Any) -> Any:
"""Deep-copy *value* replacing non-finite floats with ``None``.
Guarantees every returned envelope serializes under strict JSON (no
NaN/Infinity tokens) without silently shifting finite numbers.
"""
if isinstance(value, dict):
return {key: _json_safe(item) for key, item in value.items()}
if isinstance(value, (list, tuple)):
return [_json_safe(item) for item in value]
if isinstance(value, float) and not math.isfinite(value):
return None
return value
def _is_int(value: Any) -> bool:
"""True for real integers only (bool is explicitly excluded)."""
return isinstance(value, int) and not isinstance(value, bool)
def _parse_today(today: str | None) -> date:
"""Resolve the injected clock: ISO ``today`` string or the wall clock.
Raises ``ValueError`` for a non-string or unparseable ``today`` so the
caller can answer with an error envelope instead of a wrong date.
"""
if today is None:
return date.today()
if not isinstance(today, str):
raise ValueError(f"today must be an ISO date string or None, got {today!r}")
return date.fromisoformat(today.strip())
def _decay_fields(row, today: date) -> dict[str, Any]:
"""Read-time decay verdict for one evidence row (plan D1/D2).
Computed from the row's own ``date_ranges`` window end at query time —
never persisted. ``staleness_days`` (from ``last_verified``) is reported
alongside but NEVER gates: refreshing unchanged artifacts must not be
able to keep a row "fresh" forever.
"""
age = evidence_age_days(row.date_ranges, today)
status = classify_decay(row.date_ranges, today)
return {
"decay_status": status,
"evidence_age_days": age,
"staleness_days": staleness_days(row.last_verified, today),
"_decay_warning": decay_warning(status, age),
}
class StrategyDiscoveryFacade:
"""Read-only unified discovery surface over Alpha Zoo + SDM + evidence."""
def __init__(
self,
evidence_store: EvidenceStore | None = None,
sdm_store=None,
alpha_registry=None,
) -> None:
"""Wire the facade. Every dependency is injectable for tests.
Args:
evidence_store: Evidence backend. Default constructed lazily on
first use (``EvidenceStore()``).
sdm_store: SDM artifact store. Default resolved lazily through
``src.strategy_store._shared.get_store()``.
alpha_registry: Alpha Zoo registry. Default resolved lazily via
the process-wide shared
``src.factors.registry.get_default_registry()`` singleton —
constructing a ``Registry()`` per facade instance would re-run
the AST scan of every zoo module (~0.85s) on each construction.
"""
self._evidence_store = evidence_store
self._sdm_store = sdm_store
self._alpha_registry = alpha_registry
self._evidence_store_failed = False
self._sdm_failed = False
self._alpha_failed = False
# -- lazy dependency resolution -------------------------------------------
def _get_evidence_store(self) -> EvidenceStore | None:
"""Return the evidence store, constructing the default lazily."""
if self._evidence_store is None and not self._evidence_store_failed:
try:
self._evidence_store = EvidenceStore()
except Exception: # noqa: BLE001 — degrade, never crash the facade
logger.warning(
"EvidenceStore default construction failed; evidence lookups "
"degrade to empty results",
exc_info=True,
)
self._evidence_store_failed = True
return self._evidence_store
def _get_sdm_store(self) -> Any:
"""Return the SDM store, lazily importing the shared singleton."""
if self._sdm_store is None and not self._sdm_failed:
try:
# Local import; intentional — keeps module import dependency-free.
from src.strategy_store._shared import get_store
self._sdm_store = get_store()
except Exception: # noqa: BLE001 — degrade to zero SDM entries
logger.warning(
"SDM strategy store unavailable; SDM catalog entries degraded to none",
exc_info=True,
)
self._sdm_failed = True
return self._sdm_store
def _sdm_artifact_status(self, artifact_id: str) -> str | None:
"""Read-only SDM artifact status lookup for lifecycle mirroring.
Degrades gracefully (plan D8): a missing store, a missing
``get_artifact`` surface, or any lookup failure returns ``None``
with a logged warning — the lifecycle gate then SKIPS that row
rather than crashing or fabricating a status.
"""
store = self._get_sdm_store()
if store is None:
return None
getter = getattr(store, "get_artifact", None)
if not callable(getter):
logger.warning(
"SDM store exposes no get_artifact(); lifecycle gate skipped "
"for artifact %s",
artifact_id,
)
return None
try:
artifact = getter(artifact_id)
except Exception: # noqa: BLE001 — degrade, never crash the facade
logger.warning(
"SDM artifact lookup failed for %s; lifecycle gate skipped",
artifact_id,
exc_info=True,
)
return None
if artifact is None:
return None
status = getattr(artifact, "status", None)
status = getattr(status, "value", status)
if isinstance(status, str) and status.strip():
return status.strip().lower()
return None
def _get_alpha_registry(self) -> Any:
"""Return the Alpha Zoo registry, tolerating a failed zoo load.
The default resolution goes through the process-wide
``get_default_registry()`` singleton: building a fresh ``Registry()``
AST-scans every zoo module (~0.85s), which must not happen per facade
instance. Constructor-injected registries (tests) bypass this path.
"""
if self._alpha_registry is None and not self._alpha_failed:
try:
# Local import; intentional — zoo scan must never block package import.
from src.factors.registry import get_default_registry
self._alpha_registry = get_default_registry()
except Exception: # noqa: BLE001 — degrade to zero alphas
logger.warning(
"Alpha Zoo registry unavailable; alpha catalog entries degraded to none",
exc_info=True,
)
self._alpha_failed = True
return self._alpha_registry
# -- catalog construction --------------------------------------------------
@staticmethod
def _join_meta_list(value: Any) -> str | None:
"""Render a meta list/tuple field as a comma-joined string (or None)."""
if isinstance(value, (list, tuple)) and value:
return ", ".join(str(item) for item in value)
if isinstance(value, str) and value:
return value
return None
def _alpha_description(self, meta: dict[str, Any]) -> str | None:
"""Build a display description from alpha meta (theme + notes joined)."""
parts: list[str] = []
theme = self._join_meta_list(meta.get("theme"))
if theme:
parts.append(f"themes: {theme}")
notes = meta.get("notes")
if isinstance(notes, str) and notes.strip():
parts.append(notes.strip())
return "; ".join(parts) or None
def _alpha_summaries(self) -> list[StrategySummary]:
"""Catalog entries for every loaded Alpha Zoo alpha (sorted)."""
registry = self._get_alpha_registry()
if registry is None:
return []
try:
alpha_ids = registry.list()
except Exception: # noqa: BLE001 — degrade to zero alphas
logger.warning("Alpha Zoo registry listing failed", exc_info=True)
return []
summaries: list[StrategySummary] = []
for alpha_id in alpha_ids:
try:
alpha = registry.get(alpha_id)
except Exception: # noqa: BLE001 — skip a broken entry, keep the rest
logger.warning("Alpha Zoo entry %s unreadable", alpha_id, exc_info=True)
continue
meta = getattr(alpha, "meta", None) or {}
summaries.append(
StrategySummary(
strategy_id=f"alpha_zoo:{alpha.id}",
name=meta.get("nickname") or alpha.id,
source="alpha_zoo",
description=self._alpha_description(meta),
status=None,
universe=self._join_meta_list(meta.get("universe")),
)
)
summaries.sort(key=lambda summary: summary.strategy_id)
return summaries
def _sdm_summaries(self) -> list[StrategySummary]:
"""Catalog entries for every SDM artifact (sorted)."""
store = self._get_sdm_store()
if store is None:
return []
try:
try:
artifacts = store.list_artifacts(limit=_SDM_SCAN_LIMIT)
except TypeError:
# Injected fakes may expose a no-arg list_artifacts().
artifacts = store.list_artifacts()
except Exception: # noqa: BLE001 — degrade to zero SDM entries
logger.warning("SDM artifact listing failed", exc_info=True)
return []
summaries: list[StrategySummary] = []
for artifact in artifacts:
try:
status = getattr(artifact.status, "value", artifact.status)
signal_definition = getattr(artifact, "signal_definition", None) or None
summaries.append(
StrategySummary(
strategy_id=f"sdm:{artifact.id}",
name=str(artifact.name),
source="sdm",
description=(
signal_definition[:300] if signal_definition else None
),
status=status if status is not None else None,
universe=getattr(artifact, "universe", None),
)
)
except Exception: # noqa: BLE001 — skip a broken entry, keep the rest
logger.warning("SDM artifact unreadable", exc_info=True)
continue
summaries.sort(key=lambda summary: summary.strategy_id)
return summaries
def _evidence_by_strategy(self) -> dict[str, tuple[str, ...]]:
"""Map strategy_id -> sorted regimes that have evidence rows."""
store = self._get_evidence_store()
grouped: dict[str, set[str]] = {}
if store is None:
return {}
try:
for row in store.get_rows():
grouped.setdefault(row.strategy_id, set()).add(row.regime)
except Exception: # noqa: BLE001 — evidence enrichment is best-effort
logger.warning(
"Evidence enrichment lookup failed; omitting evidence flags",
exc_info=True,
)
return {}
return {
strategy_id: tuple(sorted(regimes))
for strategy_id, regimes in grouped.items()
}
# -- public API --------------------------------------------------------------
def list_strategies(
self,
limit: int = 20,
offset: int = 0,
source: str | None = None,
) -> dict:
"""Unified catalog: alpha_zoo entries first, then sdm entries."""
if not _is_int(limit) or limit <= 0:
return _error("limit must be a positive integer")
if not _is_int(offset) or offset < 0:
return _error("offset must be a non-negative integer")
if source is not None and source not in _VALID_SOURCES:
return _error(
f"source must be one of {'|'.join(_VALID_SOURCES)} or omitted, got {source!r}"
)
try:
items: list[StrategySummary] = []
if source in (None, "alpha_zoo"):
items.extend(self._alpha_summaries())
if source in (None, "sdm"):
items.extend(self._sdm_summaries())
evidence_map = self._evidence_by_strategy()
enriched: list[StrategySummary] = []
for summary in items:
regimes = evidence_map.get(summary.strategy_id, ())
enriched.append(
dataclasses.replace(
summary,
has_evidence=bool(regimes),
regimes_with_evidence=regimes,
)
)
page = enriched[offset : offset + limit]
envelope: dict[str, Any] = {
"status": "ok",
"total": len(enriched),
"returned": len(page),
"offset": offset,
"source": source,
"items": [dataclasses.asdict(summary) for summary in page],
}
return _json_safe(envelope)
except Exception: # noqa: BLE001 — never raise from the public facade
logger.exception("list_strategies failed")
return _error("list_strategies failed internally; see logs")
def query_strategies(
self,
regime: str | None = None,
min_sharpe: float | None = None,
min_evidence_quality: str = "adequate",
min_trades: int = 10,
cost_feasible: bool = True,
limit: int = 10,
include_stale: bool = False,
today: str | None = None,
) -> dict:
"""Evidence-gated query: only rows backed by stored evidence qualify.
Gate order (plan D9): quality floor → min_trades → cost_feasible
(fail-closed null) → min_sharpe → decay gate (stale rows excluded
unless ``include_stale=True``) → SDM lifecycle gate (``sdm:*`` rows
whose artifact status is decayed/disabled are ALWAYS excluded from
recommendations). Decay is computed at read time from each row's
``date_ranges`` window end (``evidence_age_days`` drives;
``last_verified`` / ``staleness_days`` are reported, never gating).
``today`` (ISO string) injects the clock for deterministic tests.
"""
if regime is not None and regime not in REGIMES:
return _error(
f"unknown regime {regime!r}; valid regimes: {', '.join(REGIMES)}"
)
if min_evidence_quality != "any" and min_evidence_quality not in QUALITY_ORDER:
return _error(
"min_evidence_quality must be one of "
f"{', '.join(sorted(QUALITY_ORDER))} or 'any'"
)
if not _is_int(min_trades) or min_trades < 0:
return _error("min_trades must be a non-negative integer")
if min_sharpe is not None and not (
isinstance(min_sharpe, (int, float))
and not isinstance(min_sharpe, bool)
and math.isfinite(min_sharpe)
):
return _error("min_sharpe must be a finite number or None")
if not _is_int(limit) or limit <= 0:
return _error("limit must be a positive integer")
if not isinstance(include_stale, bool):
return _error("include_stale must be a boolean")
try:
today_date = _parse_today(today)
except ValueError as exc:
return _error(str(exc))
try:
store = self._get_evidence_store()
rows = []
table_empty = True
if store is not None:
try:
rows = store.get_rows(regime=regime)
except Exception: # noqa: BLE001 — degrade to no evidence
logger.warning(
"Evidence query failed; returning no evidence rows",
exc_info=True,
)
rows = []
table_empty = True
else:
try:
table_empty = store.row_count() == 0
except Exception: # noqa: BLE001 — keep the fetched rows
logger.warning(
"Evidence row count failed; inferring emptiness "
"from the fetched rows",
exc_info=True,
)
table_empty = len(rows) == 0
quality_floor = (
QUALITY_ORDER[min_evidence_quality]
if min_evidence_quality != "any"
else -1
)
def passes(row) -> bool:
if QUALITY_ORDER.get(row.evidence_quality, 0) < quality_floor:
return False
if row.trades_in_regime < min_trades:
return False
if cost_feasible and (
row.breakeven_fee_bps is None or row.cost_sensitive
):
# Fail-closed: a null breakeven means the cost screen is
# unverifiable (multi-position run), which is not a pass.
return False
if min_sharpe is not None and (
row.sharpe_in_regime is None or row.sharpe_in_regime < min_sharpe
):
return False
return True
below_floor = 0
decay_by_key: dict[tuple[str, str], dict[str, Any]] = {}
survivors: list[Any] = []
for row in rows:
if not passes(row):
below_floor += 1
continue
survivors.append(row)
stale_excluded = 0
post_decay: list[Any] = []
for row in survivors:
decay = _decay_fields(row, today_date)
decay_by_key[(row.strategy_id, row.regime)] = decay
if decay["decay_status"] == DECAY_STALE and not include_stale:
stale_excluded += 1
continue
post_decay.append(row)
lifecycle_excluded = 0
filtered: list[Any] = []
for row in post_decay:
if row.strategy_id.startswith("sdm:"):
status = self._sdm_artifact_status(row.strategy_id.split(":", 1)[1])
if status in _SDM_EXCLUDED_STATUSES:
lifecycle_excluded += 1
continue
filtered.append(row)
filtered.sort(
key=lambda row: (
decay_by_key[(row.strategy_id, row.regime)]["decay_status"]
== DECAY_STALE,
-QUALITY_ORDER.get(row.evidence_quality, 0),
-row.trades_in_regime,
row.strategy_id,
row.regime,
)
)
items: list[dict[str, Any]] = []
for row in filtered[:limit]:
data = dataclasses.asdict(row)
decay = decay_by_key[(row.strategy_id, row.regime)]
data["decay_status"] = decay["decay_status"]
data["evidence_age_days"] = decay["evidence_age_days"]
data["staleness_days"] = decay["staleness_days"]
if decay["_decay_warning"] is not None:
data["warnings"] = [*data["warnings"], decay["_decay_warning"]]
borderline = self._is_borderline(row)
data["borderline"] = borderline
if borderline:
data["warnings"] = [*data["warnings"], _BORDERLINE_WARNING]
items.append(data)
envelope: dict[str, Any] = {
"status": "ok",
"count": len(filtered),
"returned": len(items),
"filters": {
"regime": regime,
"min_sharpe": min_sharpe,
"min_evidence_quality": min_evidence_quality,
"min_trades": min_trades,
"cost_feasible": cost_feasible,
"include_stale": include_stale,
},
"stale_excluded": stale_excluded,
"lifecycle_excluded": lifecycle_excluded,
"items": items,
}
if table_empty:
envelope["note"] = _EMPTY_EVIDENCE_NOTE
elif rows and not filtered:
# D11: non-empty table, zero rows pass — say WHY, so the
# agent can tell users what to fix instead of staring at an
# unexplained empty list.
envelope["note"] = (
"Evidence exists but every row was excluded by gates: "
f"{below_floor} below the quality/cost/trades/Sharpe "
f"floors, {stale_excluded} stale-excluded, "
f"{lifecycle_excluded} lifecycle-excluded. Use "
"include_stale=true to inspect stale rows; "
"lifecycle-excluded rows stay out of recommendations "
"(inspect them with get_strategy_evidence). Re-backtest "
"over a recent window and run refresh_strategy_evidence "
"to reinstate stale evidence."
)
return _json_safe(envelope)
except Exception: # noqa: BLE001 — never raise from the public facade
logger.exception("query_strategies failed")
return _error("query_strategies failed internally; see logs")
def get_strategy_evidence(
self, strategy_id: str, regime: str | None = None, today: str | None = None
) -> dict:
"""Full per-regime evidence breakdown for one strategy.
Inspection surface (plan D10): returns ALL rows unfiltered — decay
and lifecycle state are surfaced as fields/notes, never used to drop
rows here. Each row gains the read-time decay fields
(``decay_status`` / ``evidence_age_days`` / ``staleness_days``) plus
the decay warning; ``sdm:*`` strategies additionally carry a
``lifecycle_note`` when the SDM artifact status is decayed/disabled
(lookup failure degrades to omitting the note, never a crash).
``today`` (ISO string) injects the clock for deterministic tests.
"""
if not isinstance(strategy_id, str) or not strategy_id.strip():
return _error("strategy_id is required (non-empty string)")
if regime is not None and regime not in REGIMES:
return _error(
f"unknown regime {regime!r}; valid regimes: {', '.join(REGIMES)}"
)
try:
today_date = _parse_today(today)
except ValueError as exc:
return _error(str(exc))
try:
rows = []
store = self._get_evidence_store()
if store is not None:
try:
rows = store.get_rows(strategy_id=strategy_id, regime=regime)
except Exception: # noqa: BLE001 — degrade to no evidence
logger.warning(
"Evidence lookup failed for %s; returning no rows",
strategy_id,
exc_info=True,
)
rows = []
lifecycle_note: str | None = None
if strategy_id.startswith("sdm:"):
status = self._sdm_artifact_status(strategy_id.split(":", 1)[1])
if status in _SDM_EXCLUDED_STATUSES:
lifecycle_note = (
f"{_SDM_LIFECYCLE_PREFIX} SDM artifact status is "
f"'{status}' — excluded from default recommendations "
"regardless of evidence freshness"
)
rendered: list[dict[str, Any]] = []
for row in rows:
data = dataclasses.asdict(row)
decay = _decay_fields(row, today_date)
data["decay_status"] = decay["decay_status"]
data["evidence_age_days"] = decay["evidence_age_days"]
data["staleness_days"] = decay["staleness_days"]
if decay["_decay_warning"] is not None:
data["warnings"] = [*data["warnings"], decay["_decay_warning"]]
if lifecycle_note is not None:
data["lifecycle_note"] = lifecycle_note
rendered.append(data)
envelope: dict[str, Any] = {
"status": "ok",
"strategy_id": strategy_id,
"regime": regime,
"found": bool(rows),
"rows": rendered,
}
if strategy_id.startswith("sdm:"):
try:
sdm = self._get_sdm_store()
artifact = sdm.get_artifact(strategy_id.split(":", 1)[1]) if sdm else None
except Exception:
logger.warning("SDM description unavailable", exc_info=True)
artifact = None
if artifact is not None:
envelope["description"] = {
key: getattr(artifact, key, None) for key in (
"name", "universe", "signal_definition", "entry_rules", "exit_rules",
"position_sizing", "derived_from", "run_dir", "signal_engine_path",
)
}
if lifecycle_note is not None:
envelope["lifecycle_note"] = lifecycle_note
if not rows:
scope = f" in regime {regime!r}" if regime is not None else ""
envelope["note"] = (
f"No evidence rows found for strategy_id {strategy_id!r}{scope}. "
"Evidence rows are written by `refresh_strategy_evidence` "
"(agent/MCP tool, or the CLI `vibe-trading strategy-evidence "
"refresh`) over reproducible run artifacts."
)
return _json_safe(envelope)
except Exception: # noqa: BLE001 — never raise from the public facade
logger.exception("get_strategy_evidence failed")
return _error("get_strategy_evidence failed internally; see logs")
# -- internals ---------------------------------------------------------------
@staticmethod
def _is_borderline(row) -> bool:
"""True when a passing row sits inside the #969 adversarial buffer bands."""
if row.trades_in_regime < MIN_TRADES + BORDERLINE_TRADE_BUFFER:
return True
if (
row.breakeven_fee_bps is not None
and row.breakeven_fee_bps < BORDERLINE_BREAKEVEN_BPS
):
return True
coverage = coverage_days_from_ranges(row.date_ranges)
if coverage < MIN_COVERAGE_DAYS + BORDERLINE_COVERAGE_BUFFER_DAYS:
return True
return False