minima-cli 0.4.9__py3-none-any.whl

minima/recommender/score.py

@@ -0,0 +1,318 @@
+"""Scoring: capability prior + memory -> predicted success; cost; slider -> threshold."""
+
+from __future__ import annotations
+
+import math
+import random
+
+from minima.memory.records import clamp01
+from minima.recommender.types import ModelAggregate
+from minima.schemas.common import TaskType
+from minima.schemas.models_catalog import ModelCard
+
+_DEFAULT_PRIOR = 0.5
+
+
+def capability_prior(card: ModelCard, task_type: TaskType) -> float:
+    """Prior probability that this model handles this task type well, in [0, 1]."""
+    by_type = card.capability_by_task_type.get(task_type)
+    if by_type is not None:
+        return clamp01(by_type)
+    intel = card.capability_priors.get("intelligence_index")
+    return clamp01(intel) if intel is not None else _DEFAULT_PRIOR
+
+
+def predicted_success(
+    agg: ModelAggregate | None, prior: float, pseudocount: float
+) -> tuple[float, float]:
+    """Beta-smoothed success blended with the capability prior.
+
+    Returns ``(predicted_success, confidence)``. With no evidence, predicted success
+    falls back to the prior and confidence is 0.
+    """
+    alpha0 = prior * pseudocount
+    beta0 = (1.0 - prior) * pseudocount
+    if agg is None or agg.weight_sum <= 0.0:
+        return clamp01(prior), 0.0
+    p = (agg.weighted_success + alpha0) / (agg.weight_sum + alpha0 + beta0)
+    confidence = 1.0 - 1.0 / (1.0 + agg.weight_sum)
+    return clamp01(p), clamp01(confidence)
+
+
+def estimate_cost(
+    card: ModelCard,
+    input_tokens: int,
+    output_tokens: int,
+    use_cache: bool = False,
+    cache_fraction: float = 0.0,
+) -> tuple[float, dict[str, float]]:
+    """Flat token estimate. ``use_cache`` prices input fully at the cache-read rate (caching
+    is REQUIRED); ``cache_fraction`` in (0,1] is the lever-aware blend — assume that fraction
+    of input is served from cache at the read rate, the rest at the full rate."""
+    if use_cache and card.cache_read_cost_per_mtok is not None:
+        in_price = card.cache_read_cost_per_mtok
+    elif cache_fraction > 0.0 and card.cache_read_cost_per_mtok is not None:
+        f = min(1.0, cache_fraction)
+        in_price = f * card.cache_read_cost_per_mtok + (1.0 - f) * card.input_cost_per_mtok
+    else:
+        in_price = card.input_cost_per_mtok
+    cost_in = (input_tokens / 1_000_000.0) * in_price
+    cost_out = (output_tokens / 1_000_000.0) * card.output_cost_per_mtok
+    breakdown = {"input": round(cost_in, 8), "output": round(cost_out, 8)}
+    return cost_in + cost_out, breakdown
+
+
+def choose_cost_basis(
+    aggs_by_id: dict[str, ModelAggregate | None],
+    use_observed: bool,
+    require_caching: bool,
+    min_cost_n: int,
+) -> str:
+    """Pick ONE cost basis for the whole candidate set so costs are compared like-for-like.
+
+    Returns the best tier EVERY candidate can support:
+    - ``"rescaled"``: observed output-token behavior priced for THIS request (size-exact AND
+      reasoning-aware) — when every candidate has >= ``min_cost_n`` output-token observations.
+    - ``"observed"``: robust median realized $/call (reasoning-aware, size-approximate) — when
+      every candidate has >= ``min_cost_n`` cost observations and caching is not requested
+      (recalled history is non-cached, so the cache-aware estimate is the right basis there).
+    - ``"estimate"``: flat (cache-aware) token estimate — cold-start / mixed-evidence fallback.
+    """
+    if not use_observed:
+        return "estimate"
+    aggs = list(aggs_by_id.values())
+    if not aggs:
+        return "estimate"
+    if all(a is not None and a.observed_output_tokens(min_cost_n) is not None for a in aggs):
+        return "rescaled"
+    if not require_caching and all(
+        a is not None and a.observed_cost(min_cost_n) is not None for a in aggs
+    ):
+        return "observed"
+    return "estimate"
+
+
+def rescaled_cost(
+    card: ModelCard, agg: ModelAggregate, input_tokens: int, use_cache: bool, min_cost_n: int
+) -> float | None:
+    """Re-scale observed output behavior to the current request: this request's input tokens at
+    the (cache-aware) input rate + the model's observed median output tokens at the output rate.
+    None when there aren't enough output-token observations.
+    """
+    out_tokens = agg.observed_output_tokens(min_cost_n)
+    if out_tokens is None:
+        return None
+    if use_cache and card.cache_read_cost_per_mtok is not None:
+        in_price = card.cache_read_cost_per_mtok
+    else:
+        in_price = card.input_cost_per_mtok
+    cost_in = (input_tokens / 1_000_000.0) * in_price
+    cost_out = (out_tokens / 1_000_000.0) * card.output_cost_per_mtok
+    return cost_in + cost_out
+
+
+def effective_cost(
+    card: ModelCard,
+    agg: ModelAggregate | None,
+    input_tokens: int,
+    output_tokens: int,
+    use_cache: bool,
+    basis: str,
+    min_cost_n: int,
+    cache_fraction: float = 0.0,
+) -> tuple[float, dict[str, float]]:
+    """Cost used for ranking, on the caller-chosen ``basis`` (homogeneous across candidates).
+
+    The token estimate assumes a fixed completion length, so it understates models that spend
+    many output tokens on internal reasoning/thinking. ``"rescaled"`` re-prices observed output
+    behavior for this request; ``"observed"`` uses the robust median realized $/call; both fall
+    through to the (cache-aware) ``estimate`` when their evidence is absent.
+    """
+    if basis == "rescaled" and agg is not None:
+        rc = rescaled_cost(card, agg, input_tokens, use_cache, min_cost_n)
+        if rc is not None:
+            obs_out = agg.observed_output_tokens(min_cost_n) or 0.0
+            return rc, {"rescaled": round(rc, 8), "obs_output_tokens": round(obs_out, 1)}
+    if basis == "observed" and agg is not None:
+        observed = agg.observed_cost(min_cost_n)
+        if observed is not None:
+            return observed, {"observed_avg": round(observed, 8)}
+    return estimate_cost(card, input_tokens, output_tokens, use_cache, cache_fraction)
+
+
+def effective_cost_band(
+    card: ModelCard,
+    agg: ModelAggregate | None,
+    input_tokens: int,
+    use_cache: bool,
+    basis: str,
+    min_cost_n: int,
+    q_low: float = 0.25,
+    q_high: float = 0.75,
+) -> tuple[tuple[float, float], str] | None:
+    """Data-grounded predictable cost band ``((low, high), basis_label)`` matching the ranking
+    ``basis`` — the honest range behind the point ``effective_cost``. ``"rescaled"`` re-prices
+    the observed output-token band for this request (input fixed, output the band); ``"observed"``
+    uses the realized $/call band directly. Returns ``None`` for the ``"estimate"`` basis or when
+    evidence is below ``min_cost_n`` — the caller renders "no range yet" rather than fabricating.
+    """
+    if agg is None:
+        return None
+    label = f"p{int(round(q_low * 100))}_p{int(round(q_high * 100))}"
+    if basis == "rescaled":
+        band = agg.observed_output_tokens_band(min_cost_n, q_low, q_high)
+        if band is not None:
+            lo_out, hi_out = band
+            in_price = (
+                card.cache_read_cost_per_mtok
+                if use_cache and card.cache_read_cost_per_mtok is not None
+                else card.input_cost_per_mtok
+            )
+            cost_in = (input_tokens / 1_000_000.0) * in_price
+            lo = cost_in + (lo_out / 1_000_000.0) * card.output_cost_per_mtok
+            hi = cost_in + (hi_out / 1_000_000.0) * card.output_cost_per_mtok
+            return (lo, hi), f"rescaled_{label}"
+    if basis == "observed":
+        band = agg.observed_cost_band(min_cost_n, q_low, q_high)
+        if band is not None:
+            return band, f"observed_{label}"
+    return None
+
+
+def threshold_from_slider(
+    cost_quality_tradeoff: float, tau_min: float, tau_max: float, min_quality: float | None = None
+) -> float:
+    """Map the 0..10 slider to a minimum acceptable predicted-success threshold.
+
+    0 = accept the cheapest model clearing ``tau_min``; 10 = require ``tau_max``.
+    """
+    cq = max(0.0, min(10.0, cost_quality_tradeoff))
+    tau = tau_min + (cq / 10.0) * (tau_max - tau_min)
+    if min_quality is not None:
+        tau = max(tau, min_quality)
+    return tau
+
+
+def with_exploration_bonus(predicted: float, confidence: float, bonus: float) -> float:
+    """Optimistically inflate predicted success for under-explored candidates.
+
+    The bonus is scaled by ``(1 - confidence)`` so well-evidenced models are barely
+    touched while models with little/no recalled evidence get the full nudge — enough
+    to occasionally clear the threshold and earn a recommendation (and thus feedback).
+    ``bonus`` of 0 disables exploration entirely (pure exploitation).
+    """
+    if bonus <= 0.0:
+        return predicted
+    return clamp01(predicted + bonus * (1.0 - clamp01(confidence)))
+
+
+def ranking_score(predicted: float, normalized_cost: float, cost_quality_tradeoff: float) -> float:
+    """Smooth blend used to order the returned list (distinct from the hard threshold)."""
+    cq = max(0.0, min(10.0, cost_quality_tradeoff))
+    lam = 0.3 + 0.07 * cq  # cq=0 -> 0.3 (cost-leaning); cq=10 -> 1.0 (quality-only)
+    return lam * predicted - (1.0 - lam) * normalized_cost
+
+
+def ucb_score(
+    predicted: float,
+    interval_width: float,
+    normalized_cost: float,
+    cost_quality_tradeoff: float,
+    alpha: float,
+) -> float:
+    """Upper-confidence-bound contextual-bandit score (optimism-in-the-face-of-uncertainty).
+
+    Same cost/quality scalarization as :func:`ranking_score`, but the success term gets an
+    optimism bonus of ``alpha * half-width`` so under-explored arms are favoured for
+    exploration. Used by the SHADOW bandit policy (logged for regret comparison, never
+    overrides the deployed conjugate pick).
+    """
+    cq = max(0.0, min(10.0, cost_quality_tradeoff))
+    lam = 0.3 + 0.07 * cq
+    optimistic = clamp01(predicted + alpha * 0.5 * interval_width)
+    return lam * optimistic - (1.0 - lam) * normalized_cost
+
+
+def posterior_interval_width(
+    agg: ModelAggregate | None, prior: float, pseudocount: float
+) -> float:
+    """Approximate 95% credible-interval width of the Beta-smoothed success estimate.
+
+    Normal approximation on the posterior mean: width = 2 * 1.96 * sqrt(p(1-p)/n_eff)
+    where n_eff = weight_sum + pseudocount. With no evidence the width is maximal (1.0) —
+    "we know nothing" reads as full uncertainty, the natural escalation signal.
+    """
+    p, _ = predicted_success(agg, prior, pseudocount)
+    n_eff = (agg.weight_sum if agg is not None else 0.0) + max(pseudocount, 1e-9)
+    width = 2.0 * 1.96 * (max(p * (1.0 - p), 1e-9) / n_eff) ** 0.5
+    return min(1.0, width)
+
+
+def softmax_propensities(
+    scores: dict[str, float], argmin_id: str, epsilon: float, temperature: float
+) -> dict[str, float]:
+    """Selection propensities for the epsilon-softmax policy over the eligible set.
+
+    pi(m) = (1 - eps) * 1[m == argmin] + eps * softmax(score(m) / temperature).
+    The deterministic policy is the eps=0 special case (degenerate vector). Returned
+    propensities sum to 1 over the eligible candidates.
+    """
+    if not scores:
+        return {}
+    t = max(temperature, 1e-6)
+    peak = max(scores.values())
+    exps = {mid: math.exp((s - peak) / t) for mid, s in scores.items()}
+    total = sum(exps.values()) or 1.0
+    soft = {mid: e / total for mid, e in exps.items()}
+    eps = max(0.0, min(1.0, epsilon))
+    return {
+        mid: (1.0 - eps) * (1.0 if mid == argmin_id else 0.0) + eps * soft[mid]
+        for mid in scores
+    }
+
+
+def beta_params(
+    agg: ModelAggregate | None, prior: float, pseudocount: float
+) -> tuple[float, float]:
+    """Beta posterior (alpha, beta) for a candidate's success — the conjugate of
+    :func:`predicted_success` (whose mean is alpha / (alpha + beta)). Both are floored at a
+    tiny positive value so they are valid Beta parameters for sampling.
+    """
+    alpha0 = prior * pseudocount
+    beta0 = (1.0 - prior) * pseudocount
+    if agg is None or agg.weight_sum <= 0.0:
+        return max(alpha0, 1e-6), max(beta0, 1e-6)
+    alpha = agg.weighted_success + alpha0
+    beta = (agg.weight_sum - agg.weighted_success) + beta0
+    return max(alpha, 1e-6), max(beta, 1e-6)
+
+
+def thompson_select(
+    items: list[tuple[str, float, float, float]],
+    tau: float,
+    rng: random.Random,
+    samples: int = 128,
+) -> tuple[str, dict[str, float]]:
+    """Posterior-sampling (Thompson) selection over the cost-aware objective.
+
+    ``items`` is ``(model_id, alpha, beta, est_cost_usd)`` per candidate. Each Monte-Carlo
+    round samples theta_m ~ Beta(alpha_m, beta_m) and picks the cheapest model whose sampled
+    success clears ``tau`` (falling back to the highest sampled success when none clears).
+    The selection frequencies ARE the propensities (so IPW/off-policy evaluation stay valid),
+    and the returned pick is sampled proportional to those frequencies — consistent with them.
+    """
+    if not items:
+        return "", {}
+    counts = {m: 0 for m, _, _, _ in items}
+    for _ in range(max(1, samples)):
+        theta = {m: rng.betavariate(a, b) for m, a, b, _ in items}
+        clears = [(m, cost) for m, _, _, cost in items if theta[m] >= tau]
+        if clears:
+            pick = min(clears, key=lambda mc: (mc[1], -theta[mc[0]]))[0]
+        else:
+            pick = max(items, key=lambda it: theta[it[0]])[0]
+        counts[pick] += 1
+    total = sum(counts.values()) or 1
+    propensities = {m: counts[m] / total for m in counts}
+    pick_id = rng.choices(list(counts), weights=[counts[m] for m in counts], k=1)[0]
+    return pick_id, propensities

minima/recommender/types.py

@@ -0,0 +1,166 @@
+"""Internal dataclasses shared across the recommender stages."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from minima.memory.records import RecalledEvidence
+from minima.schemas.common import DecisionBasis
+from minima.schemas.models_catalog import ModelCard
+
+
+def _weighted_quantile(pairs: list[tuple[float, float]], q: float) -> float:
+    """Lower weighted q-quantile of (value, weight) pairs (robust to outliers)."""
+    items = sorted(pairs, key=lambda vw: vw[0])
+    total = sum(w for _, w in items)
+    q = max(0.0, min(1.0, q))
+    if total <= 0.0:  # all-zero weights -> plain positional quantile
+        vals = [v for v, _ in items]
+        idx = min(len(vals) - 1, int(q * len(vals)))
+        return vals[idx]
+    target, acc = total * q, 0.0
+    for value, weight in items:
+        acc += weight
+        if acc >= target:
+            return value
+    return items[-1][0]
+
+
+def _weighted_median(pairs: list[tuple[float, float]]) -> float:
+    """Lower weighted median of (value, weight) pairs (robust to outliers)."""
+    return _weighted_quantile(pairs, 0.5)
+
+
+@dataclass(slots=True)
+class ModelAggregate:
+    """Weighted summary of recalled outcomes for one candidate model."""
+
+    model_id: str
+    weight_sum: float = 0.0
+    weighted_success: float = 0.0
+    n: int = 0
+    avg_knowledge_confidence: float = 0.0
+    evidence: list[RecalledEvidence] = field(default_factory=list)
+
+    @property
+    def weighted_success_rate(self) -> float:
+        if self.weight_sum <= 0:
+            return 0.0
+        return self.weighted_success / self.weight_sum
+
+    def observed_cost(self, min_n: int) -> float | None:
+        """Robust realized $/call over cost-bearing neighbors: a similarity-weighted MEDIAN.
+
+        A realized cost is an objective measurement, so it is weighted by topical similarity
+        only — NOT by the staleness/knowledge-confidence factors that legitimately discount the
+        *success* signal (a past call's dollar amount doesn't get cheaper because the record is
+        old). The median keeps a single mis-recorded or pathological cost_usd (wrong units, a
+        cumulative total, a timed-out retry) from dominating. Returns None when fewer than
+        ``min_n`` recalled neighbors carry a positive cost.
+        """
+        pairs = [
+            (ev.record.cost_usd, max(0.0, ev.score))
+            for ev in self.evidence
+            if ev.record is not None and ev.record.cost_usd and ev.record.cost_usd > 0.0
+        ]
+        if len(pairs) < min_n:
+            return None
+        return _weighted_median(pairs)
+
+    def observed_output_tokens(self, min_n: int) -> float | None:
+        """Robust median realized OUTPUT tokens/call (incl. reasoning/thinking) over neighbors.
+
+        Captures the model's true output behavior on similar tasks — the part a flat token
+        estimate misses — so cost can be re-scaled to the current request's input size while
+        keeping the realized output (thinking) volume. Similarity-weighted median; None when
+        fewer than ``min_n`` recalled neighbors carry an output-token count.
+        """
+        pairs = [
+            (float(ev.record.output_tokens), max(0.0, ev.score))
+            for ev in self.evidence
+            if ev.record is not None and ev.record.output_tokens and ev.record.output_tokens > 0
+        ]
+        if len(pairs) < min_n:
+            return None
+        return _weighted_median(pairs)
+
+    def observed_latency_ms(self, min_n: int, q: float = 0.75) -> float | None:
+        """Robust observed latency percentile (default p75) over latency-bearing neighbors.
+
+        Like realized cost, latency is an objective measurement: weighted by topical
+        similarity only, not by staleness/knowledge-confidence. A high percentile (not
+        the median) is deliberate — SLA enforcement cares about the typical-worst case.
+        None when fewer than ``min_n`` recalled neighbors carry a latency.
+        """
+        pairs = [
+            (float(ev.record.latency_ms), max(0.0, ev.score))
+            for ev in self.evidence
+            if ev.record is not None and ev.record.latency_ms and ev.record.latency_ms > 0
+        ]
+        if len(pairs) < min_n:
+            return None
+        return _weighted_quantile(pairs, q)
+
+    def observed_cost_band(
+        self, min_n: int, q_low: float = 0.25, q_high: float = 0.75
+    ) -> tuple[float, float] | None:
+        """Robust p_low–p_high band of realized $/call (default p25–p75) — the data-grounded
+        predictable cost range. Same (cost, similarity) pairs and similarity-only weighting as
+        :meth:`observed_cost`; None when fewer than ``min_n`` neighbors carry a positive cost.
+        """
+        pairs = [
+            (ev.record.cost_usd, max(0.0, ev.score))
+            for ev in self.evidence
+            if ev.record is not None and ev.record.cost_usd and ev.record.cost_usd > 0.0
+        ]
+        if len(pairs) < min_n:
+            return None
+        return (_weighted_quantile(pairs, q_low), _weighted_quantile(pairs, q_high))
+
+    def observed_output_tokens_band(
+        self, min_n: int, q_low: float = 0.25, q_high: float = 0.75
+    ) -> tuple[float, float] | None:
+        """Robust p_low–p_high band of realized output tokens/call — for re-pricing the cost
+        band to the current request's input size (rescaled basis). None below ``min_n``."""
+        pairs = [
+            (float(ev.record.output_tokens), max(0.0, ev.score))
+            for ev in self.evidence
+            if ev.record is not None and ev.record.output_tokens and ev.record.output_tokens > 0
+        ]
+        if len(pairs) < min_n:
+            return None
+        return (_weighted_quantile(pairs, q_low), _weighted_quantile(pairs, q_high))
+
+
+@dataclass(slots=True)
+class CandidateScore:
+    card: ModelCard
+    predicted_success: float
+    confidence: float
+    est_cost_usd: float
+    est_cost_breakdown: dict[str, float]
+    decision_basis: DecisionBasis
+    evidence: list[RecalledEvidence] = field(default_factory=list)
+    score: float = 0.0
+    rationale: str = ""
+    # Observed latency percentile (ms) from recalled outcomes; None without evidence.
+    est_latency_ms: float | None = None
+    latency_basis: str = ""
+    # Data-grounded predictable cost band (low, high) matching the chosen basis; None when
+    # evidence is too thin to estimate a range. ``cost_band_basis`` labels its source
+    # (e.g. "observed_p25_p75", "rescaled_p25_p75", "heuristic").
+    est_cost_low: float | None = None
+    est_cost_high: float | None = None
+    cost_band_basis: str = ""
+    # 95% credible-interval width of the success estimate (1.0 = no evidence). Powers the
+    # routing-collapse margin guard and the harness green/amber/red confidence signal.
+    interval_width: float = 1.0
+    # Beta posterior parameters for the (uncalibrated) success estimate — used by Thompson
+    # sampling when that selection policy is enabled.
+    alpha: float = 0.0
+    beta: float = 0.0
+    # The pre-calibration, pre-exploration-bonus Beta-posterior mean — the HONEST
+    # evidence-based probability. ``predicted_success`` above is the deployed value
+    # (calibrated + exploration bonus); this raw value is what calibration is fit on,
+    # so the recalibration loop converges instead of oscillating. None when unset.
+    raw_predicted_success: float | None = None

minima/schemas/__init__.py

@@ -0,0 +1 @@
+"""Public request/response schemas (Pydantic v2)."""

minima/schemas/common.py

@@ -0,0 +1,73 @@
+"""Shared enums and request building blocks."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+
+class TaskType(StrEnum):
+    code = "code"
+    summarization = "summarization"
+    extraction = "extraction"
+    qa = "qa"
+    reasoning = "reasoning"
+    classification = "classification"
+    translation = "translation"
+    creative = "creative"
+    rag = "rag"
+    tool_use = "tool_use"
+    other = "other"
+
+
+class Difficulty(StrEnum):
+    trivial = "trivial"
+    easy = "easy"
+    medium = "medium"
+    hard = "hard"
+    expert = "expert"
+
+
+class OutcomeLabel(StrEnum):
+    success = "success"
+    partial = "partial"
+    failure = "failure"
+
+
+class DecisionBasis(StrEnum):
+    """Which path produced a recommendation."""
+
+    memory = "memory"  # driven by empirical recalled outcomes
+    prior = "prior"  # driven by capability priors (thin/no memory)
+    llm = "llm"  # cheap-LLM reasoner was consulted
+
+
+class Constraints(BaseModel):
+    """Optional hard limits a caller can place on the candidate set."""
+
+    allowed_providers: list[str] | None = None
+    candidate_models: list[str] | None = None
+    excluded_models: list[str] | None = None
+    max_cost_per_call: float | None = Field(None, ge=0, description="USD; hard filter")
+    min_quality: float | None = Field(None, ge=0, le=1, description="predicted_success floor")
+    require_prompt_caching: bool = False
+    max_latency_ms: int | None = Field(None, gt=0)
+    require_context_window: int | None = Field(None, gt=0)
+
+    def merged_over(self, base: Constraints) -> Constraints:
+        """Return self with any unset field inherited from ``base``."""
+        data = base.model_dump()
+        for key, value in self.model_dump().items():
+            if value is not None and value is not False:
+                data[key] = value
+        return Constraints(**data)
+
+
+class TaskInput(BaseModel):
+    task: str = Field(..., min_length=1, description="Raw task/prompt text; embedded by Mubit")
+    task_type: TaskType | None = None
+    difficulty: Difficulty | None = None
+    expected_input_tokens: int | None = Field(None, ge=0)
+    expected_output_tokens: int | None = Field(None, ge=0)
+    tags: list[str] = Field(default_factory=list, description="-> Mubit env_tags")

minima/schemas/feedback.py

@@ -0,0 +1,34 @@
+"""Schemas for the feedback / learning-loop endpoint."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from minima.schemas.common import OutcomeLabel
+
+
+class FeedbackRequest(BaseModel):
+    recommendation_id: str = Field(..., min_length=1)
+    chosen_model_id: str = Field(..., min_length=1, description="model actually run (may differ)")
+    outcome: OutcomeLabel
+    quality_score: float | None = Field(None, ge=0, le=1, description="caller-supplied; no judge")
+    input_tokens: int | None = Field(None, ge=0)
+    output_tokens: int | None = Field(None, ge=0)
+    actual_cost_usd: float | None = Field(None, ge=0)
+    latency_ms: int | None = Field(None, ge=0)
+    iterations: int | None = Field(
+        None, ge=0, description="agent loop turns to resolution (token-yield signal)"
+    )
+    verified_in_production: bool = False
+    notes: str | None = None
+    idempotency_key: str | None = None
+
+
+class FeedbackResponse(BaseModel):
+    accepted: bool
+    record_id: str | None = None
+    reinforced_entry_ids: list[str] = Field(default_factory=list)
+    updated_confidence: float | None = None
+    reflection_triggered: bool = False
+    lesson_promoted: bool = False
+    warnings: list[str] = Field(default_factory=list)

minima/schemas/models_catalog.py

@@ -0,0 +1,36 @@
+"""Schemas for the model catalog endpoint."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from minima.schemas.common import TaskType
+
+
+class ModelCard(BaseModel):
+    model_config = ConfigDict(protected_namespaces=())
+
+    model_id: str
+    provider: str
+    display_name: str = ""
+    input_cost_per_mtok: float = Field(..., ge=0)
+    output_cost_per_mtok: float = Field(..., ge=0)
+    cache_read_cost_per_mtok: float | None = None
+    supports_prompt_caching: bool = False
+    context_window: int = 0
+    max_output_tokens: int | None = None
+    capability_priors: dict[str, float] = Field(default_factory=dict)
+    capability_by_task_type: dict[TaskType, float] = Field(default_factory=dict)
+    cost_source: str = ""
+    cost_fetched_at: datetime | None = None
+    cost_stale: bool = False
+    capability_source: str = ""
+
+
+class ModelsResponse(BaseModel):
+    models: list[ModelCard]
+    catalog_version: str
+    refreshed_at: datetime | None = None
+    stale: bool = False