minima-cli 0.4.9__py3-none-any.whl

minima/__init__.py

@@ -0,0 +1,5 @@
+"""Minima — Mubit-backed LLM model recommender (recommend-only)."""
+
+from minima.version import __version__
+
+__all__ = ["__version__"]

minima/api/__init__.py

@@ -0,0 +1 @@
+"""HTTP API layer."""

minima/api/auth.py

@@ -0,0 +1,39 @@
+"""Auth dependency: resolve the caller's Mubit API key to a TenantContext.
+
+Pass-through mode: the caller presents their own Mubit key as
+``Authorization: Bearer <mubit_api_key>``. Minima uses it directly against
+MUBIT_ENDPOINT; no Minima-issued keys, no provisioning step.
+"""
+
+from __future__ import annotations
+
+from fastapi import Request
+
+from minima.api.errors import ApiError
+from minima.tenancy.context import TenantContext
+
+
+def bearer_key(request: Request) -> str | None:
+    auth = request.headers.get("authorization", "")
+    if auth.lower().startswith("bearer "):
+        return auth[7:].strip() or None
+    return None
+
+
+async def get_tenant(request: Request) -> TenantContext:
+    key = bearer_key(request)
+    if not key:
+        raise ApiError(
+            401,
+            "Unauthorized",
+            "pass your Mubit API key as: Authorization: Bearer <key>",
+        )
+    return request.app.state.passthrough_runtime.resolve(key)
+
+
+async def get_tenant_optional(request: Request) -> TenantContext | None:
+    """Like get_tenant but returns None instead of 401 (for health probes)."""
+    key = bearer_key(request)
+    if not key:
+        return None
+    return request.app.state.passthrough_runtime.resolve(key)

minima/api/errors.py

@@ -0,0 +1,40 @@
+"""RFC7807-style problem+json error handlers."""
+
+from __future__ import annotations
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+from minima.recommender.engine import NoCandidatesError
+
+
+class ApiError(Exception):
+    """A problem+json error with an explicit status/title (e.g. auth failures)."""
+
+    def __init__(self, status: int, title: str, detail: str):
+        self.status = status
+        self.title = title
+        self.detail = detail
+        super().__init__(detail)
+
+
+def _problem(status: int, title: str, detail: str) -> JSONResponse:
+    return JSONResponse(
+        status_code=status,
+        content={"type": "about:blank", "title": title, "status": status, "detail": detail},
+        media_type="application/problem+json",
+    )
+
+
+def register_error_handlers(app: FastAPI) -> None:
+    @app.exception_handler(ApiError)
+    async def _api_error(_request: Request, exc: ApiError) -> JSONResponse:
+        return _problem(exc.status, exc.title, exc.detail)
+
+    @app.exception_handler(NoCandidatesError)
+    async def _no_candidates(_request: Request, exc: NoCandidatesError) -> JSONResponse:
+        return _problem(422, "No candidate models", str(exc))
+
+    @app.exception_handler(ValueError)
+    async def _value_error(_request: Request, exc: ValueError) -> JSONResponse:
+        return _problem(400, "Invalid request", str(exc))

minima/api/routers/__init__.py

@@ -0,0 +1 @@
+"""API route modules."""

minima/api/routers/calibration.py

@@ -0,0 +1,50 @@
+"""Calibration endpoint — is predicted_success telling the truth for this org?"""
+
+from __future__ import annotations
+
+import time
+
+from fastapi import APIRouter, Depends, Query
+
+from minima.api.auth import get_tenant
+from minima.config import Settings
+from minima.deps import get_settings
+from minima.metrics.calibration import calibration_by_task_type, cusum_flags, routing_health
+from minima.schemas.savings import CalibrationResponse
+from minima.tenancy.context import TenantContext
+
+router = APIRouter(prefix="/v1", tags=["calibration"])
+
+_SECONDS_PER_DAY = 86_400.0
+
+
+@router.get("/calibration", response_model=CalibrationResponse)
+async def calibration(
+    tenant: TenantContext = Depends(get_tenant),
+    settings: Settings = Depends(get_settings),
+    namespace: str | None = Query(None, description="restrict to one namespace lane"),
+    days: float | None = Query(None, gt=0, le=365, description="lookback window in days"),
+) -> CalibrationResponse:
+    window_days = days if days is not None else float(settings.minima_calibration_window_days)
+    since = time.time() - window_days * _SECONDS_PER_DAY
+    lane = f"{tenant.lane_prefix}:{namespace}" if namespace else None
+    rows = (
+        tenant.decision_log.rows(since=since, lane=lane)
+        if tenant.decision_log is not None
+        else []
+    )
+    return CalibrationResponse(
+        org_id=tenant.org_id,
+        since=since,
+        days=window_days,
+        namespace=namespace,
+        health=routing_health(rows),
+        reports=calibration_by_task_type(
+            rows,
+            n_bins=settings.minima_calibration_bins,
+            shrinkage_k=settings.minima_calibration_shrinkage_k,
+        ),
+        drift_flags=cusum_flags(
+            rows, k=settings.minima_cusum_k, h=settings.minima_cusum_h
+        ),
+    )

minima/api/routers/feedback.py

@@ -0,0 +1,279 @@
+"""Feedback endpoint — writes the outcome to Mubit and closes the learning loop."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+
+from fastapi import APIRouter, Depends
+
+from minima.api.auth import get_tenant
+from minima.config import Settings
+from minima.deps import get_settings
+from minima.logging import get_logger
+from minima.memory.adapter import Memory
+from minima.memory.keys import (
+    build_lesson_content,
+    lesson_upsert_key,
+    outcome_idempotency_key,
+    outcome_upsert_key,
+)
+from minima.memory.records import (
+    OutcomeRecord,
+    quality_from_outcome,
+    reconcile_quality,
+    signal_from_outcome,
+)
+from minima.recommender.decisionlog import DecisionRecord, Reconciliation
+from minima.schemas.common import OutcomeLabel
+from minima.schemas.feedback import FeedbackRequest, FeedbackResponse
+from minima.tenancy.context import TenantContext
+
+log = get_logger("minima.feedback")
+router = APIRouter(prefix="/v1", tags=["feedback"])
+
+
+def _fire_reflect(memory: Memory, lane: str, user_id: str | None) -> None:
+    async def _run() -> None:
+        try:
+            await memory.reflect(lane=lane, user_id=user_id)
+        except Exception as exc:  # noqa: BLE001
+            log.warning("reflect_failed", lane=lane, error=str(exc))
+
+    asyncio.create_task(_run())  # noqa: RUF006 — fire-and-forget, errors are logged
+
+
+@router.post("/feedback", response_model=FeedbackResponse)
+async def feedback(
+    req: FeedbackRequest,
+    tenant: TenantContext = Depends(get_tenant),
+    settings: Settings = Depends(get_settings),
+) -> FeedbackResponse:
+    memory = tenant.memory
+    # Org-scoped store: a recommendation_id minted for another org resolves to None here,
+    # so org A cannot credit or poison org B's recommendation.
+    stored = tenant.recstore.get(req.recommendation_id)
+    if stored is None:
+        # Degraded late-feedback path: the recstore TTL expired but the decision log
+        # (longer retention) still knows the recommendation. The outcome record is still
+        # written (the durable (cluster, model) upsert keeps learning); only neighbor
+        # attribution and lesson promotion are skipped — the recalled-neighbor ids lived
+        # in the recstore alone.
+        if settings.minima_late_feedback_enabled and tenant.decision_log is not None:
+            decision = tenant.decision_log.get(req.recommendation_id)
+            if decision is not None:
+                return await _late_feedback(req, tenant, decision)
+        return FeedbackResponse(accepted=False, warnings=["unknown_recommendation"])
+
+    quality = quality_from_outcome(req.outcome.value, req.quality_score)
+    quality, mismatch = reconcile_quality(req.outcome.value, quality)
+    signal = signal_from_outcome(req.outcome.value, quality)
+    is_success = req.outcome == OutcomeLabel.success
+    warnings: list[str] = []
+    if mismatch:
+        warnings.append(mismatch)
+        log.warning(
+            "quality_outcome_mismatch",
+            outcome=req.outcome.value,
+            supplied_quality=req.quality_score,
+            clamped_quality=quality,
+            model_id=req.chosen_model_id,
+            cluster=stored.task_cluster,
+        )
+
+    record = OutcomeRecord(
+        model_id=req.chosen_model_id,
+        task_type=stored.task_type,
+        difficulty=stored.difficulty,
+        task_fingerprint=stored.task_fingerprint,
+        task_cluster=stored.task_cluster,
+        input_tokens=req.input_tokens or 0,
+        output_tokens=req.output_tokens or 0,
+        cost_usd=req.actual_cost_usd or 0.0,
+        latency_ms=req.latency_ms,
+        iterations=req.iterations,
+        quality_score=quality,
+        outcome=req.outcome.value,
+        recommendation_id=req.recommendation_id,
+        verified_in_production=req.verified_in_production,
+        recorded_at=time.time(),
+    )
+    upsert_key = outcome_upsert_key(stored.task_cluster, req.chosen_model_id)
+    idem = req.idempotency_key or outcome_idempotency_key(
+        req.recommendation_id, req.chosen_model_id
+    )
+    importance = "high" if (req.verified_in_production and is_success) else "medium"
+
+    try:
+        record_id = await memory.remember_outcome(
+            content=stored.content,
+            record=record,
+            lane=stored.lane,
+            upsert_key=upsert_key,
+            idempotency_key=idem,
+            user_id=stored.user_id,
+            env_tags=stored.env_tags or None,
+            importance=importance,
+            source="human",
+        )
+    except Exception as exc:  # noqa: BLE001
+        log.warning("remember_outcome_failed", error=str(exc))
+        return FeedbackResponse(accepted=False, warnings=["memory_write_failed"])
+
+    # The upserted (cluster, model) record's id is stable across feedbacks and
+    # dereferenceable — remember it for the exact-match recall fast path.
+    if record_id and tenant.durable_refs is not None:
+        try:
+            tenant.durable_refs.upsert(
+                stored.lane, stored.task_cluster, req.chosen_model_id, record_id, record_id
+            )
+        except Exception as exc:  # noqa: BLE001 — bookkeeping must never fail feedback
+            log.warning("durable_ref_upsert_failed", error=str(exc))
+
+    neighbors = stored.neighbors_by_model.get(req.chosen_model_id, [])
+    entry_ids = [eid for (eid, _ref) in neighbors if eid]
+    primary_ref = next((ref for (_eid, ref) in neighbors if ref), None) or record_id
+
+    updated_confidence: float | None = None
+    if primary_ref:
+        try:
+            oc = await memory.record_outcome(
+                lane=stored.lane,
+                reference_id=primary_ref,
+                outcome=req.outcome.value,
+                signal=signal,
+                entry_ids=entry_ids or None,
+                user_id=stored.user_id,
+                verified_in_production=req.verified_in_production,
+                idempotency_key=f"oc:{idem}",
+                rationale=f"minima feedback {req.recommendation_id}: ran {req.chosen_model_id}",
+            )
+            value = oc.get("updated_confidence")
+            updated_confidence = float(value) if value is not None else None
+        except Exception as exc:  # noqa: BLE001
+            log.warning("record_outcome_failed", error=str(exc))
+            warnings.append("reinforcement_failed")
+
+    # Promote a verified-in-production strong success to a durable Lesson. Lessons pass
+    # the server's validation gate and feed reflect()/surface_strategies rule promotion;
+    # a per-(cluster, model) upsert_key keeps one accumulating lesson instead of flooding.
+    lesson_promoted = False
+    if (
+        settings.minima_lesson_on_verified_prod
+        and req.verified_in_production
+        and is_success
+        and quality >= settings.minima_lesson_min_quality
+    ):
+        try:
+            await memory.remember_lesson(
+                content=build_lesson_content(stored.task_cluster, req.chosen_model_id, quality),
+                lane=stored.lane,
+                upsert_key=lesson_upsert_key(stored.task_cluster, req.chosen_model_id),
+                user_id=stored.user_id,
+                env_tags=stored.env_tags or None,
+                metadata={
+                    "kind": "lesson",
+                    "task_cluster": stored.task_cluster,
+                    "model_id": req.chosen_model_id,
+                    "verified_in_production": True,
+                },
+                idempotency_key=f"lsn:{idem}",
+            )
+            lesson_promoted = True
+        except Exception as exc:  # noqa: BLE001 — lesson promotion is best-effort
+            log.warning("lesson_promotion_failed", error=str(exc))
+            warnings.append("lesson_promotion_failed")
+
+    reflection_triggered = False
+    count = tenant.lane_counter.bump(tenant.counter_key(stored.lane))
+    every = settings.minima_reflect_every_n
+    if (every > 0 and count % every == 0) or (req.verified_in_production and not is_success):
+        _fire_reflect(memory, stored.lane, stored.user_id)
+        reflection_triggered = True
+
+    _reconcile_decision(tenant, req, quality, late=False)
+
+    return FeedbackResponse(
+        accepted=True,
+        record_id=record_id,
+        reinforced_entry_ids=entry_ids,
+        updated_confidence=updated_confidence,
+        reflection_triggered=reflection_triggered,
+        lesson_promoted=lesson_promoted,
+        warnings=warnings,
+    )
+
+
+def _reconcile_decision(
+    tenant: TenantContext, req: FeedbackRequest, quality: float, *, late: bool
+) -> None:
+    """Fill the decision-log row's realized columns (best-effort analytics)."""
+    if tenant.decision_log is None:
+        return
+    try:
+        tenant.decision_log.reconcile(
+            req.recommendation_id,
+            Reconciliation(
+                model_id=req.chosen_model_id,
+                outcome=req.outcome.value,
+                quality=quality,
+                cost_usd=req.actual_cost_usd,
+                latency_ms=req.latency_ms,
+                ts=time.time(),
+                late=late,
+            ),
+        )
+    except Exception as exc:  # noqa: BLE001 — analytics must never fail feedback
+        log.warning("decision_reconcile_failed", error=str(exc))
+
+
+async def _late_feedback(
+    req: FeedbackRequest,
+    tenant: TenantContext,
+    decision: DecisionRecord,
+) -> FeedbackResponse:
+    """Accept feedback after recstore expiry: write the outcome, skip attribution."""
+    quality = quality_from_outcome(req.outcome.value, req.quality_score)
+    quality, mismatch = reconcile_quality(req.outcome.value, quality)
+    warnings = ["late_feedback_no_attribution"]
+    if mismatch:
+        warnings.append(mismatch)
+
+    record = OutcomeRecord(
+        model_id=req.chosen_model_id,
+        task_type=decision.task_type,
+        difficulty=decision.difficulty,
+        task_fingerprint=decision.fingerprint,
+        task_cluster=decision.cluster,
+        input_tokens=req.input_tokens or 0,
+        output_tokens=req.output_tokens or 0,
+        cost_usd=req.actual_cost_usd or 0.0,
+        latency_ms=req.latency_ms,
+        iterations=req.iterations,
+        quality_score=quality,
+        outcome=req.outcome.value,
+        recommendation_id=req.recommendation_id,
+        verified_in_production=req.verified_in_production,
+        recorded_at=time.time(),
+    )
+    idem = req.idempotency_key or outcome_idempotency_key(
+        req.recommendation_id, req.chosen_model_id
+    )
+    try:
+        record_id = await tenant.memory.remember_outcome(
+            content=decision.content,
+            record=record,
+            lane=decision.lane,
+            upsert_key=outcome_upsert_key(decision.cluster, req.chosen_model_id),
+            idempotency_key=idem,
+            user_id=decision.user_id,
+            env_tags=decision.env_tags or None,
+            importance="medium",
+            source="human",
+        )
+    except Exception as exc:  # noqa: BLE001
+        log.warning("late_remember_outcome_failed", error=str(exc))
+        return FeedbackResponse(accepted=False, warnings=["memory_write_failed", *warnings])
+
+    _reconcile_decision(tenant, req, quality, late=True)
+    return FeedbackResponse(accepted=True, record_id=record_id, warnings=warnings)

minima/api/routers/health.py

@@ -0,0 +1,50 @@
+"""Health endpoint — always 200; reports degraded state in the body."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, Depends
+
+from minima.api.auth import get_tenant_optional
+from minima.catalog.store import CatalogStore
+from minima.config import Settings
+from minima.deps import get_catalog_store, get_settings
+from minima.tenancy.context import TenantContext
+from minima.version import __version__
+
+router = APIRouter(prefix="/v1", tags=["health"])
+
+
+@router.get("/health")
+async def health(
+    tenant: TenantContext | None = Depends(get_tenant_optional),
+    catalog_store: CatalogStore = Depends(get_catalog_store),
+    settings: Settings = Depends(get_settings),
+) -> dict[str, Any]:
+    catalog = catalog_store.get()
+    # In multi-tenant mode an unauthenticated probe still gets service liveness; the
+    # Mubit block is reported only when a valid Minima key resolves an org's instance.
+    if tenant is None:
+        mubit: dict[str, Any] = {"reachable": None, "scope": "unauthenticated"}
+    else:
+        mubit = await tenant.memory.health()
+        mubit["endpoint"] = tenant.mubit_endpoint
+        mubit["org_id"] = tenant.org_id
+    reachable = mubit.get("reachable")
+    return {
+        "status": "ok" if reachable or reachable is None else "degraded",
+        "mubit": mubit,
+        "auth": "passthrough",
+        "catalog": {
+            "version": catalog.version,
+            "cost_source": catalog.cost_source,
+            "stale": catalog.stale,
+            "models": len(catalog.cards),
+        },
+        "reasoner": {
+            "provider": settings.minima_reasoner_provider,
+            "configured": settings.reasoner_enabled,
+        },
+        "version": __version__,
+    }

minima/api/routers/models.py

@@ -0,0 +1,42 @@
+"""Model catalog endpoint."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends
+
+from minima.catalog.store import CatalogStore
+from minima.deps import get_catalog_store
+from minima.schemas.common import TaskType
+from minima.schemas.models_catalog import ModelsResponse
+
+router = APIRouter(prefix="/v1", tags=["models"])
+
+
+@router.get("/models", response_model=ModelsResponse)
+async def list_models(
+    provider: str | None = None,
+    task_type: TaskType | None = None,
+    max_cost: float | None = None,
+    include_stale: bool = True,
+    catalog_store: CatalogStore = Depends(get_catalog_store),
+) -> ModelsResponse:
+    catalog = catalog_store.get()
+    cards = list(catalog.cards)
+
+    if provider:
+        cards = [c for c in cards if c.provider.lower() == provider.lower()]
+    if task_type is not None:
+        cards = [c for c in cards if task_type in c.capability_by_task_type]
+    if max_cost is not None:
+        cards = [c for c in cards if max(c.input_cost_per_mtok, c.output_cost_per_mtok) <= max_cost]
+    if not include_stale:
+        fresh = [c for c in cards if not c.cost_stale]
+        cards = fresh or cards  # never return empty solely due to staleness
+
+    cards.sort(key=lambda c: c.input_cost_per_mtok)
+    return ModelsResponse(
+        models=cards,
+        catalog_version=catalog.version,
+        refreshed_at=catalog.refreshed_at,
+        stale=catalog.stale,
+    )

minima/api/routers/recommend.py

@@ -0,0 +1,66 @@
+"""Recommendation endpoints (per-call and per-workflow-step)."""
+
+from __future__ import annotations
+
+import uuid
+
+from fastapi import APIRouter, Depends
+
+from minima.api.auth import get_tenant
+from minima.schemas.recommend import RecommendRequest, RecommendResponse
+from minima.schemas.workflow import (
+    StepRecommendation,
+    WorkflowRequest,
+    WorkflowResponse,
+)
+from minima.tenancy.context import TenantContext
+
+router = APIRouter(prefix="/v1", tags=["recommend"])
+
+
+@router.post("/recommend", response_model=RecommendResponse)
+async def recommend(
+    req: RecommendRequest, tenant: TenantContext = Depends(get_tenant)
+) -> RecommendResponse:
+    return await tenant.recommender.recommend(req)
+
+
+@router.post("/recommend/workflow", response_model=WorkflowResponse)
+async def recommend_workflow(
+    req: WorkflowRequest, tenant: TenantContext = Depends(get_tenant)
+) -> WorkflowResponse:
+    rec = tenant.recommender
+    steps: list[StepRecommendation] = []
+    total = 0.0
+    premium = 0.0
+    confidences: list[float] = []
+
+    for step in req.steps:
+        constraints = (
+            step.constraints.merged_over(req.constraints) if step.constraints else req.constraints
+        )
+        sub = RecommendRequest(
+            task=step.task,
+            cost_quality_tradeoff=req.cost_quality_tradeoff,
+            constraints=constraints,
+            user_id=req.user_id,
+            namespace=req.namespace,
+            allow_llm_escalation=req.allow_llm_escalation,
+        )
+        resp = await rec.recommend(sub)
+        steps.append(StepRecommendation(step_id=step.step_id, recommendation=resp))
+        total += resp.recommended_model.est_cost_usd
+        premium += max(
+            (m.est_cost_usd for m in resp.ranked),
+            default=resp.recommended_model.est_cost_usd,
+        )
+        confidences.append(resp.confidence)
+
+    confidence = sum(confidences) / len(confidences) if confidences else 0.0
+    return WorkflowResponse(
+        workflow_recommendation_id=uuid.uuid4().hex,
+        steps=steps,
+        total_est_cost_usd=round(total, 8),
+        total_est_cost_if_all_premium=round(premium, 8),
+        confidence=round(confidence, 4),
+    )

minima/api/routers/savings.py

@@ -0,0 +1,55 @@
+"""Savings endpoint — counterfactual cost accounting from the decision log.
+
+Tenant-scoped: a caller sees only their own org's decisions (the decision log handed
+to this router is already org-bound by the pass-through runtime).
+"""
+
+from __future__ import annotations
+
+import time
+
+from fastapi import APIRouter, Depends, Query
+
+from minima.api.auth import get_tenant
+from minima.metrics.calibration import routing_health
+from minima.metrics.savings import group_rows, summarize
+from minima.schemas.savings import SavingsGroup, SavingsResponse
+from minima.tenancy.context import TenantContext
+
+router = APIRouter(prefix="/v1", tags=["savings"])
+
+_SECONDS_PER_DAY = 86_400.0
+
+
+@router.get("/savings", response_model=SavingsResponse)
+async def savings(
+    tenant: TenantContext = Depends(get_tenant),
+    namespace: str | None = Query(None, description="restrict to one namespace lane"),
+    days: float = Query(30.0, gt=0, le=365, description="lookback window in days"),
+    group_by: str | None = Query(
+        None, pattern="^(cluster|task_type|lane)$", description="optional breakdown"
+    ),
+) -> SavingsResponse:
+    since = time.time() - days * _SECONDS_PER_DAY
+    lane = f"{tenant.lane_prefix}:{namespace}" if namespace else None
+    rows = (
+        tenant.decision_log.rows(since=since, lane=lane)
+        if tenant.decision_log is not None
+        else []
+    )
+    summary = summarize(rows)
+    health = routing_health(rows)
+    groups = [
+        SavingsGroup(key=key, summary=summarize(group), health=routing_health(group))
+        for key, group in sorted(group_rows(rows, group_by).items())
+    ]
+    return SavingsResponse(
+        org_id=tenant.org_id,
+        since=since,
+        days=days,
+        namespace=namespace,
+        summary=summary,
+        health=health,
+        group_by=group_by,
+        groups=groups,
+    )

minima/api/routers/strategies.py

@@ -0,0 +1,33 @@
+"""Strategy-exposure endpoint — surfaces the rules Mubit has promoted for a namespace."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from fastapi import APIRouter, Depends, Query
+
+from minima.api.auth import get_tenant
+from minima.logging import get_logger
+from minima.schemas.strategies import StrategiesResponse, Strategy
+from minima.tenancy.context import TenantContext
+
+log = get_logger("minima.strategies")
+router = APIRouter(prefix="/v1", tags=["strategies"])
+
+
+@router.get("/strategies", response_model=StrategiesResponse)
+async def strategies(
+    namespace: str | None = None,
+    lesson_types: list[str] | None = Query(default=None),
+    max_strategies: int = Query(default=5, ge=1, le=50),
+    tenant: TenantContext = Depends(get_tenant),
+) -> StrategiesResponse:
+    lane = tenant.lane(namespace)
+    raw = await tenant.memory.surface_strategies(
+        lane=lane, lesson_types=lesson_types, max_strategies=max_strategies
+    )
+    items = raw.get("strategies") if isinstance(raw, Mapping) else None
+    parsed = [Strategy.from_emergent(s) for s in (items or []) if isinstance(s, Mapping)]
+    return StrategiesResponse(
+        namespace=namespace, lane=lane, strategies=parsed, count=len(parsed)
+    )

minima/catalog/__init__.py

@@ -0,0 +1 @@
+"""Model catalog: cost (live) + capability priors (static fallback)."""