wave-alpha 0.6.0__py3-none-any.whl

wave_alpha/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.6.0"

wave_alpha/backtest/__init__.py

@@ -0,0 +1,3 @@
+from wave_alpha.backtest.universe import load_universe
+
+__all__ = ["load_universe"]

wave_alpha/backtest/brier.py

@@ -0,0 +1,53 @@
+# src/wave_alpha/backtest/brier.py
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+
+def brier_score(pairs: Sequence[tuple[float, int]]) -> float:
+    """Mean squared error between predicted probability and binary outcome.
+
+    `pairs` is a sequence of (predicted_probability, actual_outcome) where
+    actual is 0 or 1. Lower is better; range [0, 1].
+    """
+    if not pairs:
+        raise ValueError("brier_score on empty sequence")
+    return sum((p - a) ** 2 for p, a in pairs) / len(pairs)
+
+
+def reliability_bins(
+    pairs: Sequence[tuple[float, int]], *, n_bins: int = 10
+) -> list[tuple[float, int, float, float]]:
+    """Group pairs into n_bins equal-width buckets over [0, 1].
+
+    Returns a list of (bin_lower, count, mean_predicted, mean_actual) sorted by
+    bin_lower; empty bins are omitted. The last bin is closed on the right
+    (predictions of exactly 1.0 land in the last bin).
+    """
+    if n_bins < 1:
+        raise ValueError(f"n_bins must be >= 1, got {n_bins}")
+    width = 1.0 / n_bins
+    buckets: dict[int, list[tuple[float, int]]] = {}
+    for p, a in pairs:
+        idx = min(int(p / width), n_bins - 1)
+        buckets.setdefault(idx, []).append((p, a))
+    out: list[tuple[float, int, float, float]] = []
+    for idx in sorted(buckets):
+        rows = buckets[idx]
+        n = len(rows)
+        mean_p = sum(p for p, _ in rows) / n
+        mean_a = sum(a for _, a in rows) / n
+        out.append((idx * width, n, mean_p, mean_a))
+    return out
+
+
+def calibration_error(pairs: Sequence[tuple[float, int]], *, n_bins: int = 10) -> float:
+    """Expected calibration error: weighted mean |bin_mean_predicted - bin_mean_actual|.
+
+    Weight is bin sample size. Range [0, 1]; 0 = perfect calibration.
+    """
+    if not pairs:
+        raise ValueError("calibration_error on empty sequence")
+    bins = reliability_bins(pairs, n_bins=n_bins)
+    total = sum(n for _, n, _, _ in bins)
+    return sum(n * abs(mean_p - mean_a) for _, n, mean_p, mean_a in bins) / total

wave_alpha/backtest/coherence_bucket.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import Literal
+
+CoherenceBucket = Literal["full", "partial", "disagreement"]
+
+# (name, lo_inclusive, hi_exclusive). hi=1.01 to include 1.0 in "full".
+COHERENCE_BUCKETS: tuple[tuple[CoherenceBucket, float, float], ...] = (
+    ("full", 0.7, 1.01),
+    ("partial", 0.4, 0.7),
+    ("disagreement", 0.0, 0.4),
+)
+
+
+def bucket_for(coh: float) -> CoherenceBucket:
+    for name, lo, hi in COHERENCE_BUCKETS:
+        if lo <= coh < hi:
+            return name
+    return "disagreement"  # safety fallback for negative scores

wave_alpha/backtest/count_layer.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from datetime import date, timedelta
+from typing import Literal, cast
+
+from wave_alpha.backtest.coherence_bucket import bucket_for as _bucket
+
+Direction = Literal["up", "down"]
+
+
+@dataclass(frozen=True)
+class CountEvaluation:
+    """One (ticker, as_of) backtest sample for the count layer."""
+
+    ticker: str
+    as_of: date
+    predicted_direction: Direction
+    actual_direction: Direction
+    coherence_score: float
+    top1_hit: bool
+    top3_directions: tuple[Direction, ...]
+    top3_hit: bool
+
+
+@dataclass
+class CountLayerResult:
+    evaluations: list[CountEvaluation] = field(default_factory=list)
+    n_bars_forward: int = 20
+
+    @property
+    def sample_size(self) -> int:
+        return len(self.evaluations)
+
+    @property
+    def top1_hit_rate(self) -> float:
+        if not self.evaluations:
+            return 0.0
+        return sum(1 for e in self.evaluations if e.top1_hit) / len(self.evaluations)
+
+    @property
+    def top3_hit_rate(self) -> float:
+        if not self.evaluations:
+            return 0.0
+        return sum(1 for e in self.evaluations if e.top3_hit) / len(self.evaluations)
+
+    def by_coherence_bucket(self) -> dict[str, dict[str, float]]:
+        groups: dict[str, list[CountEvaluation]] = {"full": [], "partial": [], "disagreement": []}
+        for e in self.evaluations:
+            groups[_bucket(e.coherence_score)].append(e)
+        return {
+            name: {
+                "sample_size": len(rows),
+                "top1_hit_rate": (sum(1 for r in rows if r.top1_hit) / len(rows)) if rows else 0.0,
+                "top3_hit_rate": (sum(1 for r in rows if r.top3_hit) / len(rows)) if rows else 0.0,
+            }
+            for name, rows in groups.items()
+        }
+
+    def by_year(self) -> dict[int, dict[str, float]]:
+        groups: dict[int, list[CountEvaluation]] = {}
+        for e in self.evaluations:
+            groups.setdefault(e.as_of.year, []).append(e)
+        return {
+            yr: {
+                "sample_size": len(rows),
+                "top1_hit_rate": sum(1 for r in rows if r.top1_hit) / len(rows),
+                "top3_hit_rate": sum(1 for r in rows if r.top3_hit) / len(rows),
+            }
+            for yr, rows in sorted(groups.items())
+        }
+
+
+@dataclass
+class CountLayerEvaluator:
+    """Walks (ticker x as_ofs) inlining pivot detection + count enumeration,
+    derives top-1 and top-3 predicted directions, compares to actual
+    n_bars-forward direction, and accumulates a CountLayerResult.
+
+    Bypasses pipeline.run_analysis entirely — count enumeration is invoked
+    directly so the LLM seam is never reached. Backtest is reproducible
+    without an API key by construction.
+    """
+
+    provider: object  # OHLCVProvider — typed as object to avoid circular import
+    n_bars_forward: int = 20
+
+    def evaluate(self, ticker: str, as_ofs: Iterable[date]) -> CountLayerResult:
+        # Fetch ALL bars once — the as_of filter is applied per-eval via
+        # PointInTimeView. fetch(end=last_as_of + buffer) so forward history
+        # is available for label computation.
+        from wave_alpha.data.provider import OHLCVProvider
+        from wave_alpha.domain import Interval
+
+        as_of_list = list(as_ofs)
+        if not as_of_list:
+            return CountLayerResult(evaluations=[], n_bars_forward=self.n_bars_forward)
+
+        provider: OHLCVProvider = self.provider  # type: ignore[assignment]
+
+        # Buffer = 2x n_bars_forward to ensure enough forward history.
+        end = max(as_of_list) + timedelta(days=self.n_bars_forward * 3)
+        daily_all = provider.fetch(ticker, Interval.DAILY, end=end)
+        weekly_all = provider.fetch(ticker, Interval.WEEKLY, end=end)
+        h4_all = provider.fetch(ticker, Interval.HOURLY_4, end=end)
+
+        result = CountLayerResult(evaluations=[], n_bars_forward=self.n_bars_forward)
+        for as_of in as_of_list:
+            ev = self._evaluate_one(
+                ticker=ticker,
+                as_of=as_of,
+                daily_all=daily_all,
+                weekly_all=weekly_all,
+                h4_all=h4_all,
+            )
+            if ev is not None:
+                result.evaluations.append(ev)
+        return result
+
+    def _evaluate_one(
+        self,
+        *,
+        ticker: str,
+        as_of: date,
+        daily_all: list,
+        weekly_all: list,
+        h4_all: list,
+    ) -> CountEvaluation | None:
+        from wave_alpha.backtest.labels import forward_direction_label
+        from wave_alpha.coherence.score import (
+            CoherenceInputs,
+            predicted_direction,
+            three_way,
+        )
+        from wave_alpha.data.point_in_time import (
+            LookaheadError,
+            PointInTimeView,
+            UnsortedBarsError,
+        )
+        from wave_alpha.domain import Interval
+
+        actual = forward_direction_label(daily_all, as_of=as_of, n_bars=self.n_bars_forward)
+        if actual is None:
+            return None
+        try:
+            daily_view = PointInTimeView(daily_all, as_of).visible()
+            weekly_view = PointInTimeView(weekly_all, as_of).visible() if weekly_all else []
+            h4_view = PointInTimeView(h4_all, as_of).visible() if h4_all else []
+        except (LookaheadError, UnsortedBarsError):
+            raise
+        except Exception:
+            return None
+        if not daily_view:
+            return None
+
+        counts_daily = self._counts_for(daily_view, Interval.DAILY)
+        if not counts_daily:
+            return None
+        counts_weekly = self._counts_for(weekly_view, Interval.WEEKLY) if weekly_view else []
+        counts_h4 = self._counts_for(h4_view, Interval.HOURLY_4) if h4_view else []
+
+        coh = three_way(
+            CoherenceInputs(
+                weekly=counts_weekly[0] if counts_weekly else None,
+                daily=counts_daily[0] if counts_daily else None,
+                hourly4=counts_h4[0] if counts_h4 else None,
+            )
+        )
+
+        top1_dir = predicted_direction(counts_daily[0])
+        if top1_dir is None:
+            return None
+        top1_hit = top1_dir == actual
+
+        top3 = []
+        for c in counts_daily[:3]:
+            d = predicted_direction(c)
+            if d is not None:
+                top3.append(d)
+        top3_hit = actual in top3
+
+        return CountEvaluation(
+            ticker=ticker,
+            as_of=as_of,
+            predicted_direction=cast(Direction, top1_dir),
+            actual_direction=actual,
+            coherence_score=coh.score,
+            top1_hit=top1_hit,
+            top3_directions=tuple(cast(Direction, d) for d in top3),
+            top3_hit=top3_hit,
+        )
+
+    def _counts_for(self, bars: list, interval: object) -> list:
+        from wave_alpha.elliott.enumerator import enumerate_counts
+        from wave_alpha.pipeline import _DEFAULT_ATR_MULTIPLES, _DEFAULT_DEGREE_FOR_COUNT
+        from wave_alpha.pivots.multi_degree import detect_multi_degree
+
+        if not bars:
+            return []
+        by_degree = detect_multi_degree(
+            bars,
+            interval=interval,  # type: ignore[arg-type]
+            atr_multiples=_DEFAULT_ATR_MULTIPLES,
+        )
+        pivots = by_degree.get(_DEFAULT_DEGREE_FOR_COUNT, [])
+        return enumerate_counts(pivots, degree=_DEFAULT_DEGREE_FOR_COUNT, top_k=5)

wave_alpha/backtest/grid.py

@@ -0,0 +1,294 @@
+"""Ablation grid harness: cartesian-product TradeRules sweeps over
+run_trade_layer.
+
+Spec: docs/superpowers/specs/2026-05-06-ablation-grid-design.md
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass, field
+from itertools import product
+from typing import Any, Literal
+
+from wave_alpha.backtest.runner import BacktestConfig, run_trade_layer
+from wave_alpha.backtest.trade_layer import TradeLayerResult
+from wave_alpha.data.provider import OHLCVProvider
+from wave_alpha.trades.models import TradeRules
+
+
+@dataclass(frozen=True)
+class GridAxis:
+    """One sweep dimension. `levels` are the values to sweep; each level
+    must be a TradeRules-compatible value for the field named `name`."""
+
+    name: str
+    levels: list[Any]
+
+
+@dataclass(frozen=True)
+class GridConfig:
+    """Declarative grid definition. `axes` are swept; `fixed` are held
+    constant across all cells. The cartesian product of axis levels
+    produces the grid's cells."""
+
+    axes: list[GridAxis]
+    fixed: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        axis_names = [ax.name for ax in self.axes]
+        seen: set[str] = set()
+        for name in axis_names:
+            if name in seen:
+                raise ValueError(f"duplicate axis name: {name!r}")
+            seen.add(name)
+        overlap = seen & self.fixed.keys()
+        if overlap:
+            raise ValueError(f"axis name(s) also in fixed: {sorted(overlap)!r}")
+
+    def cells(self) -> Iterator[GridCell]:
+        """Yield GridCell instances in row-major axis order."""
+        level_lists = [axis.levels for axis in self.axes]
+        for combo in product(*level_lists):
+            axis_values = {axis.name: level for axis, level in zip(self.axes, combo, strict=True)}
+            yield GridCell(axis_values=axis_values, fixed=dict(self.fixed))
+
+
+@dataclass(frozen=True)
+class GridCell:
+    """One sweep cell: combined axis values + fixed values. `cell_id`
+    is deterministic from axis values for reproducible artifact paths."""
+
+    axis_values: dict[str, Any]
+    fixed: dict[str, Any]
+
+    @property
+    def cell_id(self) -> str:
+        """Deterministic ID from axis values, joined by underscores.
+
+        Example: entry-immediate_dir-long_minconf-0.45
+        Lists are joined with hyphens; floats keep their string repr.
+        """
+        parts: list[str] = []
+        for name, value in self.axis_values.items():
+            short_name = _short_axis_name(name)
+            short_value = _short_axis_value(value)
+            parts.append(f"{short_name}-{short_value}")
+        return "_".join(parts)
+
+    def trade_rules_kwargs(self) -> dict[str, Any]:
+        """Merge axis_values + fixed into a TradeRules() kwargs dict."""
+        return {**self.fixed, **self.axis_values}
+
+
+_AXIS_NAME_SHORT = {
+    "entry_trigger": "entry",
+    "stop_source": "stop",
+    "target_source": "target",
+    "direction_modes": "dir",
+    "min_confidence": "minconf",
+}
+
+
+def _short_axis_name(name: str) -> str:
+    return _AXIS_NAME_SHORT.get(name, name)
+
+
+def _short_axis_value(value: Any) -> str:
+    if isinstance(value, list):
+        if value == ["long"]:
+            return "long"
+        if value == ["long", "short"]:
+            return "both"
+        return "-".join(str(v) for v in value)
+    if isinstance(value, str):
+        return value.replace("_", "-")
+    return str(value)
+
+
+# ---------------------------------------------------------------------------
+# Cross-cell aggregation
+# ---------------------------------------------------------------------------
+
+SAMPLE_SIZE_FLOOR = 200
+
+
+@dataclass(frozen=True)
+class GridResultRow:
+    """One cell's outcome: the cell's identity + the trade-layer result it produced."""
+
+    cell: GridCell
+    result: TradeLayerResult
+
+
+@dataclass
+class GridResult:
+    """Cross-cell aggregation. `rows` are in cell-iteration order from
+    GridConfig.cells(); aggregation methods rank, slice, and summarize."""
+
+    rows: list[GridResultRow] = field(default_factory=list)
+
+    def ranked_by_expectancy(self, *, sample_floor: int = SAMPLE_SIZE_FLOOR) -> list[GridResultRow]:
+        """Rows with closed_trades >= sample_floor, sorted by expectancy descending."""
+        eligible = [r for r in self.rows if r.result.closed_trades >= sample_floor]
+        return sorted(eligible, key=lambda r: r.result.expectancy, reverse=True)
+
+    def winner(self, *, sample_floor: int = SAMPLE_SIZE_FLOOR) -> GridResultRow | None:
+        """Highest-expectancy row meeting the sample-size floor; None if no row qualifies."""
+        ranked = self.ranked_by_expectancy(sample_floor=sample_floor)
+        return ranked[0] if ranked else None
+
+    def axis_sensitivity(self) -> dict[str, dict[str, dict[str, float]]]:
+        """For each axis, marginal mean of headline metrics at each level.
+
+        Returns: {axis_name: {level_str: {metric_name: mean_value}}}
+        Metrics: expectancy, profit_factor, closed_trades.
+        Levels are stringified via _short_axis_value for stable keys.
+
+        Profit-factor mean handling:
+        - If a level has at least one finite-PF cell, the mean is the
+          average of those finite cells (inf cells excluded so they don't
+          drag the mean toward zero).
+        - If ALL cells at a level have inf PF (every cell zero-loss), the
+          mean surfaces as inf — uniformly degenerate-positive. Coercing
+          to 0.0 would be the opposite of the truth.
+        - If the level has no cells at all (impossible after the cartesian
+          product but a defensive case), the mean is 0.0.
+
+        Raises ValueError if rows do not all share the same axis set.
+        """
+        if not self.rows:
+            return {}
+        first_axes = list(self.rows[0].cell.axis_values.keys())
+        expected = set(first_axes)
+        for i, row in enumerate(self.rows):
+            if set(row.cell.axis_values.keys()) != expected:
+                raise ValueError(
+                    f"row {i} has axes {set(row.cell.axis_values.keys())}; "
+                    f"expected {expected}. axis_sensitivity requires all rows "
+                    f"share the same axis set."
+                )
+        out: dict[str, dict[str, dict[str, float]]] = {}
+        for axis_name in first_axes:
+            level_groups: dict[str, list[GridResultRow]] = {}
+            for row in self.rows:
+                level = row.cell.axis_values[axis_name]
+                key = _short_axis_value(level)
+                level_groups.setdefault(key, []).append(row)
+            out[axis_name] = {
+                level_key: {
+                    "expectancy": _mean(r.result.expectancy for r in group),
+                    "profit_factor": _pf_mean(group),
+                    "closed_trades": _mean(r.result.closed_trades for r in group),
+                }
+                for level_key, group in level_groups.items()
+            }
+        return out
+
+
+def _mean(values: Iterable[float]) -> float:
+    vals = list(values)
+    return sum(vals) / len(vals) if vals else 0.0
+
+
+def _pf_mean(group: list[GridResultRow]) -> float:
+    """Mean profit_factor for a group of rows.
+
+    A finite mean if any cell has finite PF (inf cells excluded so they
+    don't drag the average toward zero). If every cell is degenerate
+    (PF == inf), surface inf — the level is uniformly zero-loss.
+    Empty group → 0.0 (defensive).
+    """
+    pfs = [row.result.profit_factor for row in group]
+    if not pfs:
+        return 0.0
+    finite = [pf for pf in pfs if pf != float("inf")]
+    if not finite:
+        return float("inf")
+    return sum(finite) / len(finite)
+
+
+# ---------------------------------------------------------------------------
+# Phase-1 GO/NO-GO trigger
+# ---------------------------------------------------------------------------
+
+PHASE1_EXPECTANCY_THRESHOLD = 0.05
+PHASE1_PF_THRESHOLD = 1.05
+
+
+def phase1_trigger(
+    result: GridResult,
+    *,
+    expectancy_threshold: float = PHASE1_EXPECTANCY_THRESHOLD,
+    pf_threshold: float = PHASE1_PF_THRESHOLD,
+    sample_floor: int = SAMPLE_SIZE_FLOOR,
+) -> tuple[Literal["GO", "NO-GO"], str]:
+    """GO iff at least one cell has (expectancy >= expectancy_threshold OR
+    profit_factor >= pf_threshold) AND closed_trades >= sample_floor.
+
+    Returns (verdict, human-readable reason for the spec §6.2 fill).
+    """
+    qualifying: list[GridResultRow] = []
+    for row in result.rows:
+        if row.result.closed_trades < sample_floor:
+            continue
+        pf = row.result.profit_factor
+        # Treat inf PF as qualifying (zero-loss cell — passes by definition,
+        # but we surface it explicitly rather than silently coercing).
+        pf_qualifies = pf == float("inf") or pf >= pf_threshold
+        if row.result.expectancy >= expectancy_threshold or pf_qualifies:
+            qualifying.append(row)
+    if not qualifying:
+        # Identify the best-effort summary for the NO-GO reason
+        best_eligible = result.winner()
+        if best_eligible is None:
+            return (
+                "NO-GO",
+                f"No cell met the sample-size floor (closed_trades >= {sample_floor}).",
+            )
+        best_pf = best_eligible.result.profit_factor
+        best_pf_str = "∞" if best_pf == float("inf") else f"{best_pf:.2f}"
+        return (
+            "NO-GO",
+            f"Best eligible cell: expectancy={best_eligible.result.expectancy:+.3f}R, "
+            f"PF={best_pf_str}, "
+            f"closed_trades={best_eligible.result.closed_trades}. "
+            f"Threshold: expectancy >= +{expectancy_threshold:.2f}R "
+            f"OR PF >= {pf_threshold:.2f}.",
+        )
+    top = max(qualifying, key=lambda r: r.result.expectancy)
+    top_pf = top.result.profit_factor
+    top_pf_str = "∞" if top_pf == float("inf") else f"{top_pf:.2f}"
+    return (
+        "GO",
+        f"Best qualifying cell: expectancy={top.result.expectancy:+.3f}R, "
+        f"PF={top_pf_str}, "
+        f"closed_trades={top.result.closed_trades}. "
+        f"Cell axes: {top.cell.axis_values}.",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Grid orchestration
+# ---------------------------------------------------------------------------
+
+
+def run_grid(
+    grid_config: GridConfig,
+    *,
+    base_cfg: BacktestConfig,
+    provider: OHLCVProvider,
+) -> GridResult:
+    """Iterate over cells in row-major axis order; per cell, build a
+    TradeRules from the cell's axis_values + fixed values and call
+    run_trade_layer. Aggregate into a GridResult.
+
+    The grid is a thin orchestration on top of run_trade_layer; per-cell
+    numerical correctness is the trade-sim layer's contract.
+    """
+    rows: list[GridResultRow] = []
+    for cell in grid_config.cells():
+        rules = TradeRules.model_validate(cell.trade_rules_kwargs())
+        result = run_trade_layer(base_cfg, provider=provider, rules=rules)
+        rows.append(GridResultRow(cell=cell, result=result))
+    return GridResult(rows=rows)

wave_alpha/backtest/grid_report.py

@@ -0,0 +1,106 @@
+"""Markdown renderer for cross-cell GridResult summaries.
+
+Spec: docs/superpowers/specs/2026-05-06-ablation-grid-design.md §3.8.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from wave_alpha.backtest.grid import (
+    SAMPLE_SIZE_FLOOR,
+    GridConfig,
+    GridResult,
+    phase1_trigger,
+)
+
+
+def render_grid_markdown(
+    result: GridResult,
+    *,
+    config: GridConfig,
+    phase_name: str,
+) -> str:
+    """Render the grid result as a markdown report with sections:
+    header, per-cell summary, axis sensitivity, verdict.
+    """
+    lines: list[str] = []
+    lines.append("# Grid Sweep Report")
+    lines.append("")
+    lines.append(f"_generated {datetime.now(UTC).isoformat(timespec='seconds')}_")
+    lines.append("")
+    lines.append(f"**{phase_name}** — {len(result.rows)} cells")
+    axes_str = " x ".join(f"{a.name}({len(a.levels)})" for a in config.axes)
+    lines.append(f"**Axes:** {axes_str}")
+    if config.fixed:
+        fixed_str = ", ".join(f"{k}={v}" for k, v in config.fixed.items())
+        lines.append(f"**Held fixed:** {fixed_str}")
+    lines.append("")
+
+    # Per-cell summary
+    lines.append("## Per-cell summary")
+    lines.append("")
+    lines.append("| cell_id | n | hit | avg R | expectancy | PF |")
+    lines.append("|---|---:|---:|---:|---:|---:|")
+    for row in result.rows:
+        n = row.result.closed_trades
+        hit = row.result.hit_rate
+        avg_r = row.result.avg_R
+        exp = row.result.expectancy
+        pf = row.result.profit_factor
+        pf_s = "∞" if pf == float("inf") else f"{pf:.2f}"
+        lines.append(
+            f"| {row.cell.cell_id} | {n} | {hit:.2f} | {avg_r:+.2f} | {exp:+.2f} | {pf_s} |"
+        )
+    lines.append("")
+
+    # Axis sensitivity
+    lines.append("## Axis sensitivity")
+    lines.append("")
+    lines.append("| axis | level | mean expectancy | mean PF | mean closed_trades |")
+    lines.append("|---|---|---:|---:|---:|")
+    sens = result.axis_sensitivity()
+    for axis_name, levels in sens.items():
+        for level_key, metrics in levels.items():
+            pf_val = metrics["profit_factor"]
+            pf_s = "∞" if pf_val == float("inf") else f"{pf_val:.2f}"
+            lines.append(
+                f"| {axis_name} | {level_key} | "
+                f"{metrics['expectancy']:+.3f} | "
+                f"{pf_s} | "
+                f"{int(metrics['closed_trades'])} |"
+            )
+    lines.append("")
+
+    # Verdict (only meaningful for Phase 1; harmless for Phase 2)
+    lines.append("## Verdict")
+    lines.append("")
+    winner = result.winner()
+    if winner is None:
+        lines.append(
+            f"**No winner.** No cell met the sample-size floor "
+            f"(closed_trades >= {SAMPLE_SIZE_FLOOR})."
+        )
+    else:
+        winner_pf = winner.result.profit_factor
+        winner_pf_s = "∞" if winner_pf == float("inf") else f"{winner_pf:.2f}"
+        lines.append(
+            f"**Best cell:** `{winner.cell.cell_id}` — "
+            f"expectancy={winner.result.expectancy:+.3f}R, "
+            f"PF={winner_pf_s}, "
+            f"n={winner.result.closed_trades}"
+        )
+        lines.append("")
+        lines.append("**Axis values:**")
+        for k, v in winner.cell.axis_values.items():
+            lines.append(f"- `{k}` = `{v}`")
+    lines.append("")
+
+    if phase_name.lower().startswith("phase 1"):
+        verdict, reason = phase1_trigger(result)
+        lines.append(f"**Phase 1 trigger:** **{verdict}**")
+        lines.append("")
+        lines.append(f"_{reason}_")
+        lines.append("")
+
+    return "\n".join(lines)