"""Shared reporting math and formatting.

One definition of every delta so summaries, regression reports, and the

dashboard cannot disagree about what "vs baseline" means:

- delta_pct: POSITIVE means the value is LOWER/BETTER than the baseline

  (used by summary tables labelled "positive deltas mean better").

- slower_pct / lower_is_better_pct: POSITIVE means the value is HIGHER/WORSE

  than the baseline (used by regression flagging).

"""

from __future__ import annotations

import math

import statistics

from typing import Any, Optional

from oakbench.stats import percentile_nearest

def delta_pct(base: float, value: float) -> float:

    if base == 0:

        return 0.0

    return ((base - value) / base) * 100.0

def slower_pct(baseline: Optional[float], value: Optional[float]) -> Optional[float]:

    if baseline is None or value is None or baseline <= 0:

        return None

    return ((value - baseline) / baseline) * 100.0

def symmetric_ratio_spread_pct(left: Optional[float], right: Optional[float]) -> Optional[float]:

    """Null-control spread with no privileged subject or denominator."""

    if left is None or right is None or not all(math.isfinite(value) and value > 0 for value in (left, right)):

        return None

    return slower_pct(min(left, right), max(left, right))

def lower_is_better_pct(baseline: Optional[float], value: Optional[float]) -> Optional[float]:

    if baseline is None or value is None or baseline <= 0:

        return None

    return ((value - baseline) / baseline) * 100.0

def delta_ms(baseline: Optional[float], value: Optional[float]) -> Optional[float]:

    if baseline is None or value is None:

        return None

    return value - baseline

# Minimum sample counts for a nearest-rank tail percentile to be more than a

# relabelled max: below 1/(1-p) samples the percentile IS the max. Reporting

# null instead (ADR-0002) keeps tail claims honest at small n.

TAIL_PERCENTILE_MIN_SAMPLES = {"p95": 20, "p99": 100}

def tail_latency_summary(values: list[float]) -> dict[str, Any]:

    """p50/p95/p99/max with sample-count honesty.

    Agents pay tail latency as stuck tool calls and timeouts; medians hide it.

    Unsupportable percentiles are null, and `tail_supported` says which levels

    this sample count can claim.

    """

    n = len(values)

    summary: dict[str, Any] = {

        "n": n,

        "p50_ms": median(values),

        "max_ms": max(values) if values else None,

    }

    supported: list[str] = []

    for label, pct in (("p95", 95.0), ("p99", 99.0)):

        if n >= TAIL_PERCENTILE_MIN_SAMPLES[label]:

            summary[f"{label}_ms"] = percentile_nearest(values, pct)

            supported.append(label)

        else:

            summary[f"{label}_ms"] = None

    summary["tail_supported"] = supported

    return summary

def median(values: list[float]) -> Optional[float]:

    if not values:

        return None

    return float(statistics.median(values))

def fmt_ms(value: Optional[float]) -> str:

    if value is None:

        return ""

    return f"{value:.1f}"

def fmt_num(value: Optional[float], precision: int = 1) -> str:

    if value is None:

        return ""

    return f"{value:.{precision}f}"

def fmt_pct(value: Optional[float]) -> str:

    if value is None:

        return ""

    return f"{value:+.1f}%"

def fmt_rate(value: float) -> str:

    return f"{value * 100.0:.1f}%"

def fmt_delta_lower_better(base: Optional[float], value: Optional[float], skip: bool = False) -> str:

    """Render delta_pct (positive = better) or empty when not comparable."""

    if skip or base is None or value is None:

        return ""

    return f"{delta_pct(base, value):+.1f}%"