Skip to content

"Vibe-Trading: Your Personal Trading Agent"

17.3 KB
Raw Blame
"""Pure data models and threshold logic for strategy-discovery evidence.

This module is intentionally I/O-free so it can be imported cheaply and unit
tested without a database or the network. It defines the two frozen dataclasses
(``EvidenceRow``, ``StrategySummary``) that flow between the evidence store,
the evidence harness, and the facade, plus the small set of pure helper
functions used to classify evidence quality, compute the sizing-corrected
breakeven fee, and derive the month-granularity date coverage span.

The numeric thresholds here are the single source of truth for what counts as
``adequate`` / ``marginal`` / ``insufficient`` evidence. The facade and the
harness import these constants rather than re-deriving them, so the #969
adversarial borders (buffered "borderline" bands) stay consistent everywhere.
"""

from __future__ import annotations

import math
import re
from dataclasses import dataclass, field
from datetime import date, timedelta

# ---------------------------------------------------------------------------
# Regime vocabulary
# ---------------------------------------------------------------------------

#: Canonical market-regime labels. Evidence rows must carry exactly one of
#: these; ``EvidenceRow.__post_init__`` rejects anything else.
REGIMES = ("bear_market", "bull_market", "structural")

#: Evidence-stage ladder (issue #969 discussion, initial-d). Every row names
#: the stage of the pipeline that produced it; today only ``backtest`` is
#: written (the harness computes over backtest artifacts), the remaining
#: stages are reserved so holdout/shadow/live evidence can join later
#: without a schema change.
EVIDENCE_STAGES = (
    "hypothesis",
    "backtest",
    "holdout",
    "shadow",
    "live_canary",
    "retired",
)

#: Stages that assert a computed result. A row at one of these stages claims
#: evidence that something reproduced it, so it must name that something:
#: ``__post_init__`` refuses to build one with an empty ``provenance``.
#: ``hypothesis`` (nothing computed yet) and ``retired`` (withdrawn) are
#: exempt — neither claims a current result.
STAGES_REQUIRING_PROVENANCE = frozenset(
    {"backtest", "holdout", "shadow", "live_canary"}
)

# ---------------------------------------------------------------------------
# Evidence-quality ladder
# ---------------------------------------------------------------------------

QUALITY_ADEQUATE = "adequate"
QUALITY_MARGINAL = "marginal"
QUALITY_INSUFFICIENT = "insufficient"

#: Ordering used to compare quality floors and to sort results best-first.
QUALITY_ORDER = {
    QUALITY_ADEQUATE: 2,
    QUALITY_MARGINAL: 1,
    QUALITY_INSUFFICIENT: 0,
}

# ---------------------------------------------------------------------------
# Thresholds (single source of truth)
# ---------------------------------------------------------------------------

#: Minimum number of trades inside a regime before the evidence can rise
#: above "insufficient".
MIN_TRADES = 10

#: Minimum calendar span (in days) of the evidence window. Below this the
#: evidence is capped at "marginal" even with plenty of trades.
MIN_COVERAGE_DAYS = 730

#: Breakeven fee (in basis points) below which a strategy is considered too
#: cost-sensitive to recommend without an explicit cost feasibility check.
COST_SENSITIVE_BREAKEVEN_BPS = 5.0

#: A row that passes the hard thresholds but sits inside these buffered bands
#: is flagged "borderline" so callers cite the raw figures, not the verdict.
BORDERLINE_TRADE_BUFFER = 5
BORDERLINE_BREAKEVEN_BPS = 10.0
BORDERLINE_COVERAGE_BUFFER_DAYS = 365

# ---------------------------------------------------------------------------
# Evidence decay vocabulary and thresholds (Phase 2, #969)
# ---------------------------------------------------------------------------

#: Decay verdict vocabulary. Computed AT READ TIME from the evidence itself
#: (window recency) — never persisted, never derived from model memory.
DECAY_FRESH = "fresh"
DECAY_AGING = "aging"
DECAY_STALE = "stale"

#: Evidence-window age (days since the latest ``date_ranges`` window ended)
#: at or above which a row is flagged ``aging``. Justified against the
#: documented quarterly re-backtest cadence: a window end more than ~90 days
#: old means the strategy has missed at least one scheduled re-verification
#: cycle, so the row carries an ``aged-evidence:`` warning — but it is NOT
#: excluded, because one missed cycle is recoverable.
DECAY_AGING_EVIDENCE_AGE_DAYS = 90

#: Evidence-window age (days) at or above which a row is ``stale`` and is
#: excluded from default recommendations. A window end more than ~180 days
#: old means at least two consecutive quarterly re-backtest cycles were
#: missed; the evidence can no longer vouch for the current market, so the
#: row is refused by default (inspectable via ``include_stale``).
#: Boundary semantics: ``age >= DECAY_STALE_EVIDENCE_AGE_DAYS`` ⇒ stale,
#: elif ``age >= DECAY_AGING_EVIDENCE_AGE_DAYS`` ⇒ aging, else fresh — the
#: exact threshold belongs to the STRICTER side (fail-closed, sergio12S).
DECAY_STALE_EVIDENCE_AGE_DAYS = 180

# ---------------------------------------------------------------------------
# Dataclasses
# ---------------------------------------------------------------------------


@dataclass(frozen=True)
class EvidenceRow:
    """A single (strategy, regime) evidence record.

    All return-like fields are decimal fractions (``0.083`` == +8.3%) so the
    facade can render them without guessing at units. Optional fields are
    ``None`` when the underlying artifact simply did not record them — we
    never invent a placeholder number.
    """

    strategy_id: str
    regime: str
    trades_in_regime: int
    #: Average deployed equity fraction in (0, 1]; ``None`` when unknown.
    position_size: float | None = None
    return_in_regime: float | None = None
    benchmark_in_regime: float | None = None
    excess_in_regime: float | None = None
    sharpe_in_regime: float | None = None
    max_drawdown_in_regime: float | None = None
    #: Each entry is "YYYY-MM to YYYY-MM". Kept as a tuple so the dataclass
    #: stays hashable / frozen-friendly.
    date_ranges: tuple[str, ...] = ()
    breakeven_fee_bps: float | None = None
    cost_sensitive: bool = False
    evidence_quality: str = QUALITY_INSUFFICIENT
    warnings: tuple[str, ...] = ()
    #: ISO date string ("YYYY-MM-DD") of the last harness verification.
    last_verified: str = ""
    #: Pipeline stage that produced this row; one of ``EVIDENCE_STAGES``.
    #: Defaults to the weakest claim: a row that says nothing about how it was
    #: produced must not read as though a backtest stood behind it.
    evidence_stage: str = "hypothesis"
    #: Reproducible artifact reference: the backtest run directory whose
    #: ``artifacts/`` this row was computed from.
    provenance: str = ""
    #: JSON string naming the regime-labeling parameters (window, bear/bull
    #: thresholds, Sharpe annualization) used when this row was computed.
    regime_definition: str = ""

    def __post_init__(self) -> None:
        if self.regime not in REGIMES:
            raise ValueError(
                f"invalid regime {self.regime!r}; expected one of {REGIMES}"
            )
        if self.evidence_stage not in EVIDENCE_STAGES:
            raise ValueError(
                f"invalid evidence_stage {self.evidence_stage!r}; "
                f"expected one of {EVIDENCE_STAGES}"
            )
        if self.evidence_stage in STAGES_REQUIRING_PROVENANCE and not self.provenance:
            raise ValueError(
                f"evidence_stage {self.evidence_stage!r} claims a computed "
                f"result, so provenance must name the run it was computed "
                f"from; got an empty provenance for strategy "
                f"{self.strategy_id!r} / regime {self.regime!r}"
            )


@dataclass(frozen=True)
class StrategySummary:
    """Catalog entry surfaced by :meth:`StrategyDiscoveryFacade.list_strategies`.

    ``source`` is ``"alpha_zoo"`` or ``"sdm"``. ``status`` mirrors the SDM
    lifecycle state and is ``None`` for alpha-zoo entries, which have no
    lifecycle.
    """

    strategy_id: str
    name: str
    source: str
    description: str | None = None
    status: str | None = None
    universe: str | None = None
    has_evidence: bool = False
    regimes_with_evidence: tuple[str, ...] = field(default=())


# ---------------------------------------------------------------------------
# Pure helpers
# ---------------------------------------------------------------------------


def _parse_month_first(token: str) -> date | None:
    """Parse a ``YYYY-MM`` token into the first day of that month."""
    token = token.strip()
    match = re.fullmatch(r"(\d{4})-(\d{1,2})", token)
    if match is None:
        return None
    year = int(match.group(1))
    month = int(match.group(2))
    if not 1 <= month <= 12:
        return None
    return date(year, month, 1)


def _month_last_day_anchor(start_of_month: date) -> date:
    """Return the last calendar day of the month containing ``start_of_month``."""
    if start_of_month.month == 12:
        return date(start_of_month.year, 12, 31)
    return date(start_of_month.year, start_of_month.month + 1, 1) - timedelta(days=1)


def coverage_days_from_ranges(date_ranges) -> int:
    """Span from the earliest range start to the latest range end, in days.

    Each entry is parsed as ``"YYYY-MM to YYYY-MM"``; the span runs from the
    first day of the earliest start month to the last day of the latest end
    month. Malformed entries contribute nothing. Returns ``0`` when no entry
    parses cleanly (an honest zero rather than a fabricated span).
    """
    min_start: date | None = None
    max_end: date | None = None

    for entry in date_ranges:
        if not isinstance(entry, str):
            continue
        pieces = [p for p in re.split(r"\s+to\s+", entry.strip(), flags=re.IGNORECASE)]
        if len(pieces) != 2:
            continue
        start = _parse_month_first(pieces[0])
        end_start = _parse_month_first(pieces[1])
        if start is None or end_start is None:
            continue
        end = _month_last_day_anchor(end_start)
        if min_start is None or start < min_start:
            min_start = start
        if max_end is None or end > max_end:
            max_end = end

    if min_start is None or max_end is None:
        return 0
    return max(0, (max_end - min_start).days)


def classify_quality(trades_in_regime: int, coverage_days: int) -> str:
    """Map (trade count, coverage span) onto the quality ladder."""
    if trades_in_regime < MIN_TRADES:
        return QUALITY_INSUFFICIENT
    if coverage_days < MIN_COVERAGE_DAYS:
        return QUALITY_MARGINAL
    return QUALITY_ADEQUATE


def evidence_window_end(date_ranges) -> date | None:
    """Last calendar day of the latest evidence window, or ``None``.

    Each entry is parsed as ``"YYYY-MM to YYYY-MM"``; the window end is the
    last day of the latest end month (month-granular ranges are end-anchored
    to month-end, see :func:`_month_last_day_anchor`). Malformed entries
    contribute nothing; ``None`` when nothing parses cleanly.
    """
    max_end: date | None = None

    for entry in date_ranges:
        if not isinstance(entry, str):
            continue
        pieces = [p for p in re.split(r"\s+to\s+", entry.strip(), flags=re.IGNORECASE)]
        if len(pieces) != 2:
            continue
        end_start = _parse_month_first(pieces[1])
        if end_start is None:
            continue
        end = _month_last_day_anchor(end_start)
        if max_end is None or end > max_end:
            max_end = end

    return max_end


def evidence_age_days(date_ranges, today: date) -> int | None:
    """Age in days of the latest evidence window relative to ``today``.

    ``today − evidence_window_end``, clamped to ``>= 0``: month-granular
    ranges are end-anchored to month-end, so a window ending in the current
    month can land in the future relative to ``today`` — a negative age is
    reported as 0 (freshest possible), never as a negative number. Returns
    ``None`` when no window end parses (callers fail closed on that).
    """
    window_end = evidence_window_end(date_ranges)
    if window_end is None:
        return None
    return max(0, (today - window_end).days)


def staleness_days(last_verified: str, today: date) -> int | None:
    """Days since the row was last verified; ``None`` for malformed input.

    Reported on every returned row but NEVER used for gating (plan D1):
    ``staleness_days`` would let a scheduled refresh of unchanged artifacts
    keep every row "fresh" forever — decay gating is driven by
    :func:`evidence_age_days` instead.
    """
    if not isinstance(last_verified, str):
        return None
    text = last_verified.strip()
    if not text:
        return None
    try:
        verified = date.fromisoformat(text[:10])
    except ValueError:
        return None
    return max(0, (today - verified).days)


def classify_decay(
    date_ranges,
    today: date,
    aging_days: int = DECAY_AGING_EVIDENCE_AGE_DAYS,
    stale_days: int = DECAY_STALE_EVIDENCE_AGE_DAYS,
) -> str:
    """Decay verdict from the evidence window recency (pure, read-time).

    Boundary semantics: ``age >= stale_days`` ⇒ ``stale``, elif
    ``age >= aging_days`` ⇒ ``aging``, else ``fresh`` — an exact threshold
    belongs to the stricter side. Unparseable/empty ``date_ranges`` classify
    as ``stale`` fail-closed: evidence whose window cannot be dated cannot
    vouch for anything (sergio12S discipline, #969).
    """
    age = evidence_age_days(date_ranges, today)
    if age is None:
        return DECAY_STALE
    if age >= stale_days:
        return DECAY_STALE
    if age >= aging_days:
        return DECAY_AGING
    return DECAY_FRESH


def decay_warning(decay_status: str, evidence_age_days: int | None) -> str | None:
    """Stable decay warning for a row, or ``None`` for fresh rows.

    Prefixes are fixed tokens (``stale-evidence:``, ``aged-evidence:``) with
    the day count in the body so downstream tools can match them without
    parsing prose. A stale verdict with an unknown age (unparseable window)
    still warns — with the unparseable reason instead of a day count.
    """
    if decay_status == DECAY_STALE:
        if evidence_age_days is None:
            return (
                "stale-evidence: evidence window end is missing or "
                "unparseable, treated as stale fail-closed — re-backtest "
                "over a recent window and refresh before relying on this row"
            )
        return (
            f"stale-evidence: evidence window ended {evidence_age_days} days "
            f"ago (>= {DECAY_STALE_EVIDENCE_AGE_DAYS}-day staleness "
            "threshold) — excluded from default recommendations; re-backtest "
            "over a recent window and refresh to reinstate"
        )
    if decay_status == DECAY_AGING:
        return (
            f"aged-evidence: evidence window ended {evidence_age_days} days "
            f"ago (>= {DECAY_AGING_EVIDENCE_AGE_DAYS}-day aging threshold) — "
            "still queryable, but verify with a fresh backtest before "
            "relying on this row"
        )
    return None


def breakeven_fee_bps(
    gross_return: float,
    trades: int,
    position_size: float | None = None,
) -> float | None:
    """Sizing-corrected breakeven transaction fee in basis points.

    Identity (per sergio12S, #969)::

        breakeven_bps = ln(1 + gross_return) / (2 * trades * position_size) * 10_000

    ``position_size`` defaults to ``1.0`` (full capital deployed) when
    ``None``. Returns ``None`` whenever the inputs are not usable (zero /
    negative trades, a return at or below -100%, a non-positive position
    size, or any non-finite value) rather than producing a meaningless or
    infinite number.
    """
    s = 1.0 if position_size is None else position_size
    try:
        gross = float(gross_return)
        n_trades = float(trades)
        size = float(s)
    except (TypeError, ValueError):
        return None

    if not (math.isfinite(gross) and math.isfinite(n_trades) and math.isfinite(size)):
        return None
    if n_trades <= 0 or gross <= -1.0 or size <= 0:
        return None

    return math.log(1.0 + gross) / (2.0 * n_trades * size) * 10_000.0


def build_warnings(
    trades_in_regime: int,
    coverage_days: int,
    breakeven: float | None,
    quality: str,
    cost_sensitive: bool,
) -> tuple[str, ...]:
    """Stable, machine-readable warning strings for an evidence row.

    Prefixes are fixed tokens (``insufficient-trades:``, ``short-coverage:``,
    ``cost-sensitive:``) so downstream tools can match them without parsing
    prose. Only conditions that actually hold emit a warning.
    """
    warnings: list[str] = []

    if trades_in_regime < MIN_TRADES:
        warnings.append(
            f"insufficient-trades: {trades_in_regime} < {MIN_TRADES} trades in regime"
        )

    if coverage_days < MIN_COVERAGE_DAYS:
        warnings.append(
            f"short-coverage: {coverage_days} days < {MIN_COVERAGE_DAYS} day window"
        )

    if cost_sensitive:
        breakeven_text = (
            f"{breakeven:.2f} bps"
            if isinstance(breakeven, float) and math.isfinite(breakeven)
            else "unknown"
        )
        warnings.append(
            f"cost-sensitive: breakeven {breakeven_text} "
            f"below {COST_SENSITIVE_BREAKEVEN_BPS:.1f} bps threshold"
        )

    return tuple(warnings)