@0dai-dev/cli 4.3.6 → 4.3.7

package/lib/python/model_router.py

@@ -0,0 +1,1434 @@
+#!/usr/bin/env python3
+"""Model routing recommendations from experience data.
+
+Analyzes historical events to recommend the best agent/model for a given
+task type, using a weighted composite score across quality, success rate,
+cost efficiency, and speed.
+
+Issue: #86
+"""
+from __future__ import annotations
+
+import dataclasses
+import json
+import logging
+import math
+import os
+import pathlib
+import sys
+from typing import Any
+
+log = logging.getLogger("0dai.model_router")
+
+# ---------------------------------------------------------------------------
+# Task-type specific weights (must sum to 1.0)
+# ---------------------------------------------------------------------------
+
+TASK_WEIGHTS: dict[str, dict[str, float]] = {
+    "feat":     {"quality": 0.35, "success": 0.30, "cost": 0.20, "speed": 0.15},
+    "fix":      {"quality": 0.30, "success": 0.40, "cost": 0.15, "speed": 0.15},
+    "refactor": {"quality": 0.45, "success": 0.30, "cost": 0.15, "speed": 0.10},
+    "test":     {"quality": 0.20, "success": 0.35, "cost": 0.30, "speed": 0.15},
+    "docs":     {"quality": 0.15, "success": 0.25, "cost": 0.35, "speed": 0.25},
+    "triage":   {"quality": 0.15, "success": 0.30, "cost": 0.35, "speed": 0.20},
+    "long_context_audit": {"quality": 0.35, "success": 0.30, "cost": 0.15, "speed": 0.20},
+    "long_context_audit_ru": {"quality": 0.35, "success": 0.30, "cost": 0.15, "speed": 0.20},
+    "cheap_triage": {"quality": 0.15, "success": 0.30, "cost": 0.35, "speed": 0.20},
+    "cheap_triage_ru": {"quality": 0.15, "success": 0.30, "cost": 0.35, "speed": 0.20},
+    "doc_generation": {"quality": 0.15, "success": 0.25, "cost": 0.35, "speed": 0.25},
+    "hotfix":   {"quality": 0.30, "success": 0.40, "cost": 0.15, "speed": 0.15},
+    "design":   {"quality": 0.45, "success": 0.30, "cost": 0.10, "speed": 0.15},
+}
+
+DEFAULT_WEIGHTS = {"quality": 0.30, "success": 0.30, "cost": 0.25, "speed": 0.15}
+
+# ---------------------------------------------------------------------------
+# Task-type provider matrix (#2198 Phase 1)
+#
+# Used for cold-start routing before enough experience data exists. Providers
+# here are dispatch providers, not necessarily CLI binary names. Existing
+# Codex/Claude paths stay present for code-heavy and reasoning-heavy work while
+# cheap/high-context direct APIs absorb mechanical and volume-heavy tasks.
+# ---------------------------------------------------------------------------
+
+TASK_PROVIDER_MATRIX: dict[str, list[dict[str, str]]] = {
+    "read": [
+        {"provider": "codex", "model": "gpt-5.4-mini", "agent": "codex", "tier": "fast", "effort": "low", "billing_class": "subscription"},
+        {"provider": "gemini-direct", "model": "gemini-2.5-flash-lite", "agent": "gemini", "tier": "fast", "effort": "low", "billing_class": "subscription"},
+    ],
+    "search": [
+        {"provider": "codex", "model": "gpt-5.4-mini", "agent": "codex", "tier": "fast", "effort": "low", "billing_class": "subscription"},
+        {"provider": "gemini-direct", "model": "gemini-2.5-flash-lite", "agent": "gemini", "tier": "fast", "effort": "low", "billing_class": "subscription"},
+    ],
+    "summary": [
+        {"provider": "codex", "model": "gpt-5.4-mini", "agent": "codex", "tier": "fast", "effort": "low", "billing_class": "subscription"},
+        {"provider": "gemini-direct", "model": "gemini-2.5-flash-lite", "agent": "gemini", "tier": "fast", "effort": "low", "billing_class": "subscription"},
+    ],
+    "test_output": [
+        {"provider": "codex", "model": "gpt-5.4-mini", "agent": "codex", "tier": "fast", "effort": "low", "billing_class": "subscription"},
+        {"provider": "gemini-direct", "model": "gemini-2.5-flash-lite", "agent": "gemini", "tier": "fast", "effort": "low", "billing_class": "subscription"},
+    ],
+    "format": [
+        {"provider": "codex", "model": "gpt-5.4-mini", "agent": "codex", "tier": "fast", "effort": "low", "billing_class": "subscription"},
+    ],
+    "small_fix": [
+        {"provider": "codex", "model": "gpt-5.4-mini", "agent": "codex", "tier": "fast", "effort": "medium", "billing_class": "subscription"},
+        {"provider": "opencode-go", "model": "opencode-go/minimax-m2.7", "agent": "opencode-go", "tier": "fast", "effort": "medium", "billing_class": "subscription"},
+    ],
+    "triage": [
+        {"provider": "deepseek", "model": "deepseek-chat", "agent": "deepseek", "tier": "balanced", "effort": "medium", "billing_class": "pay_per_use"},
+        {"provider": "openrouter", "model": "qwen/qwen3-coder", "agent": "openrouter", "tier": "fast", "effort": "low", "billing_class": "pay_per_use"},
+        {"provider": "codex", "model": "gpt-5.4-mini", "agent": "codex", "tier": "fast", "effort": "low", "billing_class": "subscription"},
+    ],
+    "long_context_audit": [
+        {"provider": "kimi", "model": "moonshotai/kimi-k2.5", "agent": "gemini", "tier": "deep", "effort": "high", "billing_class": "pay_per_use"},
+        {"provider": "gemini-direct", "model": "gemini-2.5-pro", "agent": "gemini", "tier": "deep", "effort": "high", "billing_class": "subscription"},
+    ],
+    "long_context_audit_ru": [
+        {"provider": "yandexgpt", "model": "yandexgpt", "agent": "gemini", "tier": "balanced", "effort": "medium", "billing_class": "pay_per_use"},
+        {"provider": "gemini-direct", "model": "gemini-2.5-pro", "agent": "gemini", "tier": "deep", "effort": "high", "billing_class": "subscription"},
+    ],
+    "cheap_triage_ru": [
+        {"provider": "gigachat", "model": "GigaChat-2-Pro", "agent": "deepseek", "tier": "balanced", "effort": "medium", "billing_class": "pay_per_use"},
+        {"provider": "deepseek", "model": "deepseek-chat", "agent": "deepseek", "tier": "balanced", "effort": "medium", "billing_class": "pay_per_use"},
+    ],
+    "cheap_triage": [
+        {"provider": "deepseek", "model": "deepseek-chat", "agent": "deepseek", "tier": "balanced", "effort": "medium", "billing_class": "pay_per_use"},
+        {"provider": "openrouter", "model": "qwen/qwen3-coder", "agent": "openrouter", "tier": "fast", "effort": "low", "billing_class": "pay_per_use"},
+        {"provider": "glm", "model": "accounts/fireworks/models/glm-5p1", "agent": "deepseek", "tier": "balanced", "effort": "medium", "billing_class": "pay_per_use"},
+    ],
+    "legacy_long_context_audit": [
+        {"provider": "gemini-direct", "model": "gemini-2.5-pro", "agent": "gemini", "tier": "deep", "effort": "high", "billing_class": "subscription"},
+        {"provider": "claude-opus", "model": "opus", "agent": "claude", "tier": "deep", "effort": "high", "billing_class": "subscription"},
+    ],
+    "refactor": [
+        {"provider": "codex", "model": "gpt-5.4", "agent": "codex", "tier": "balanced", "effort": "medium", "billing_class": "subscription"},
+        {"provider": "opencode-go", "model": "opencode-go/kimi-k2.6", "agent": "opencode-go", "tier": "balanced", "effort": "medium", "billing_class": "subscription"},
+    ],
+    "broad_refactor": [
+        {"provider": "openrouter", "model": "anthropic/claude-opus-4-8", "agent": "openrouter", "tier": "deep", "effort": "high", "billing_class": "pay_per_use"},
+        {"provider": "codex", "model": "gpt-5.3-codex", "agent": "codex", "tier": "deep", "effort": "high", "billing_class": "subscription"},
+        {"provider": "gemini-direct", "model": "gemini-2.5-pro", "agent": "gemini", "tier": "deep", "effort": "high", "billing_class": "subscription"},
+    ],
+    "design": [
+        {"provider": "openrouter", "model": "anthropic/claude-opus-4-8", "agent": "openrouter", "tier": "deep", "effort": "high", "billing_class": "pay_per_use"},
+        {"provider": "claude-opus", "model": "opus", "agent": "claude", "tier": "deep", "effort": "high", "billing_class": "subscription"},
+        {"provider": "claude-sonnet", "model": "sonnet", "agent": "claude", "tier": "balanced", "effort": "medium", "billing_class": "subscription"},
+    ],
+    "doc_generation": [
+        {"provider": "codex", "model": "gpt-5.4-mini", "agent": "codex", "tier": "fast", "effort": "medium", "billing_class": "subscription"},
+        {"provider": "gemini-direct", "model": "gemini-2.5-flash-lite", "agent": "gemini", "tier": "fast", "effort": "low", "billing_class": "subscription"},
+    ],
+    "hotfix": [
+        {"provider": "codex", "model": "gpt-5.4", "agent": "codex", "tier": "balanced", "effort": "medium", "billing_class": "subscription"},
+        {"provider": "claude-sonnet", "model": "sonnet", "agent": "claude", "tier": "balanced", "effort": "medium", "billing_class": "subscription"},
+    ],
+    "review": [
+        {"provider": "codex", "model": "gpt-5.4", "agent": "codex", "tier": "balanced", "effort": "medium", "billing_class": "subscription"},
+        {"provider": "gemini-direct", "model": "gemini-2.5-pro", "agent": "gemini", "tier": "balanced", "effort": "medium", "billing_class": "subscription"},
+        # #3770: cheap + premium OpenRouter options as later-tier fallbacks for
+        # the review route. Primary stays codex/gpt-5.4 so existing guardrails
+        # and budgets are unchanged.
+        {"provider": "openrouter", "model": "qwen/qwen3-coder", "agent": "openrouter", "tier": "fast", "effort": "low", "billing_class": "pay_per_use"},
+        {"provider": "openrouter", "model": "anthropic/claude-opus-4-8", "agent": "openrouter", "tier": "deep", "effort": "high", "billing_class": "pay_per_use"},
+    ],
+    "security": [
+        {"provider": "openrouter", "model": "anthropic/claude-opus-4-8", "agent": "openrouter", "tier": "deep", "effort": "high", "billing_class": "pay_per_use"},
+        {"provider": "claude-opus", "model": "opus", "agent": "claude", "tier": "deep", "effort": "high", "billing_class": "subscription"},
+        {"provider": "codex", "model": "gpt-5.3-codex", "agent": "codex", "tier": "deep", "effort": "high", "billing_class": "subscription"},
+    ],
+}
+
+TASK_PROVIDER_ALIASES: dict[str, str] = {
+    "": "refactor",
+    "general": "refactor",
+    "feat": "refactor",
+    "feature": "refactor",
+    "implement": "refactor",
+    "implementation": "refactor",
+    "fix": "hotfix",
+    "bugfix": "hotfix",
+    "small_fix": "small_fix",
+    "small-fix": "small_fix",
+    "docs": "doc_generation",
+    "doc": "doc_generation",
+    "documentation": "doc_generation",
+    "docs_typo": "doc_generation",
+    "docs-typo": "doc_generation",
+    "docs_read": "read",
+    "docs-read": "read",
+    "read": "read",
+    "reading": "read",
+    "simple": "read",
+    "simple_read": "read",
+    "simple-read": "read",
+    "search": "search",
+    "grep": "search",
+    "summary": "summary",
+    "summarize": "summary",
+    "test": "test_output",
+    "tests": "test_output",
+    "test_output": "test_output",
+    "test-output": "test_output",
+    "format": "format",
+    "formatting": "format",
+    "review": "review",
+    "code_review": "review",
+    "code-review": "review",
+    "security": "security",
+    "security_review": "security",
+    "security-review": "security",
+    "broad_refactor": "broad_refactor",
+    "broad-refactor": "broad_refactor",
+    "root_cause": "broad_refactor",
+    "root-cause": "broad_refactor",
+    "audit": "long_context_audit",
+    "long-context-audit": "long_context_audit",
+    "long_context": "long_context_audit",
+    "long_context_audit_en": "long_context_audit",
+    "long-context-audit-en": "long_context_audit",
+    "long_context_en": "long_context_audit",
+    "long_context_audit_ru": "long_context_audit_ru",
+    "long-context-audit-ru": "long_context_audit_ru",
+    "long_context_ru": "long_context_audit_ru",
+    "ru_audit": "long_context_audit_ru",
+    "audit_ru": "long_context_audit_ru",
+    "cheap_triage": "cheap_triage",
+    "cheap-triage": "cheap_triage",
+    "cheap_triage_ru": "cheap_triage_ru",
+    "cheap-triage-ru": "cheap_triage_ru",
+    "triage_ru": "cheap_triage_ru",
+    "ru_triage": "cheap_triage_ru",
+}
+
+PROVIDER_ALIASES: dict[str, str] = {
+    "gemini": "gemini-direct",
+    "gemini-direct": "gemini-direct",
+    "gemini-1.5": "gemini-direct",
+    "deepseek": "deepseek",
+    "codex": "codex",
+    "claude-opus": "claude-opus",
+    "opus": "claude-opus",
+    "claude-sonnet": "claude-sonnet",
+    "sonnet": "claude-sonnet",
+    "gigachat": "gigachat",
+    "giga-chat": "gigachat",
+    "sber": "gigachat",
+    "sberbank": "gigachat",
+    "yandexgpt": "yandexgpt",
+    "yandex-gpt": "yandexgpt",
+    "yandex": "yandexgpt",
+    "ya-gpt": "yandexgpt",
+    "glm": "glm",
+    "glm-5": "glm",
+    "glm-5.1": "glm",
+    "glm-5p1": "glm",
+    "zhipu": "glm",
+    "z-ai": "glm",
+    "kimi": "kimi",
+    "kimi-200k": "kimi",
+    "kimi-k2.5": "kimi",
+    "moonshot": "kimi",
+    "opencode-go": "opencode-go",
+    # OpenRouter unified gateway — review-bot roster (#3770). These aliases
+    # resolve provider-ONLY: every value is "openrouter", i.e. they select the
+    # gateway, not a specific model. The bare "qwen" alias is therefore NOT
+    # ambiguous between qwen3-coder and qwen3-max — it never picks a model. The
+    # concrete slug (qwen/qwen3-coder vs qwen/qwen3-max) is supplied separately
+    # (model_override / the review-bot chain) and passed straight through to
+    # OpenRouter. The qwen3-coder / qwen3-max aliases below likewise only route
+    # to the gateway; they exist so an operator typing either resolves cleanly.
+    "openrouter": "openrouter",
+    "open-router": "openrouter",
+    "or": "openrouter",
+    "qwen": "openrouter",
+    "qwen3-coder": "openrouter",
+    "qwen3-max": "openrouter",
+    "opus-4-8": "openrouter",
+    "claude-opus-4-8": "openrouter",
+}
+
+PROVIDER_BACKENDS: dict[str, dict[str, Any]] = {
+    "gigachat": {
+        "vendor": "Sber",
+        "endpoint": "https://gigachat.devices.sberbank.ru/api/v1/chat/completions",
+        "default_model": "GigaChat-2-Pro",
+        "auth_env": "GIGACHAT_AUTH_KEY",
+        "secret_path": str(pathlib.Path.home() / ".config" / "secrets" / "gigachat.env"),
+        "transport": "openai-chat-rest",
+        "context_tokens": "32k",
+    },
+    "yandexgpt": {
+        "vendor": "Yandex Cloud",
+        "endpoint": "https://llm.api.cloud.yandex.net/foundationModels/v1/completion",
+        "default_model": "yandexgpt",
+        "auth_env": "YANDEX_API_KEY",
+        "secondary_auth_env": "YANDEX_FOLDER_ID",
+        "secret_path": str(pathlib.Path.home() / ".config" / "secrets" / "yandex.env"),
+        "transport": "yandex-completion-rest",
+        "context_tokens": "32k",
+    },
+    "glm": {
+        "vendor": "Z.ai",
+        "endpoint": "https://api.fireworks.ai/inference/v1/chat/completions",
+        "fallback_endpoint": "https://openrouter.ai/api/v1/chat/completions",
+        "default_model": "accounts/fireworks/models/glm-5p1",
+        "fallback_model": "z-ai/glm-5.1",
+        "auth_env": "FIREWORKS_API_KEY",
+        "fallback_auth_env": "OPENROUTER_API_KEY",
+        "secret_path": str(pathlib.Path.home() / ".config" / "secrets" / "fireworks.env"),
+        "fallback_secret_path": str(pathlib.Path.home() / ".config" / "secrets" / "openrouter.env"),
+        "transport": "openai-chat-rest",
+        "context_tokens": "202k",
+    },
+    "kimi": {
+        "vendor": "Moonshot",
+        "endpoint": "https://openrouter.ai/api/v1/chat/completions",
+        "default_model": "moonshotai/kimi-k2.5",
+        "auth_env": "OPENROUTER_API_KEY",
+        "secret_path": str(pathlib.Path.home() / ".config" / "secrets" / "openrouter.env"),
+        "transport": "openai-chat-rest",
+        "context_tokens": "262k",
+    },
+}
+
+PROVIDER_CREDENTIALS: dict[str, dict[str, Any]] = {
+    "gigachat": {
+        "required": ("GIGACHAT_AUTH_KEY",),
+        "secret_paths": (pathlib.Path.home() / ".config" / "secrets" / "gigachat.env",),
+    },
+    "yandexgpt": {
+        "required": ("YANDEX_API_KEY", "YANDEX_FOLDER_ID"),
+        "secret_paths": (pathlib.Path.home() / ".config" / "secrets" / "yandex.env",),
+    },
+    "glm": {
+        "any_of": (("FIREWORKS_API_KEY",), ("OPENROUTER_API_KEY",)),
+        "secret_paths": (
+            pathlib.Path.home() / ".config" / "secrets" / "fireworks.env",
+            pathlib.Path.home() / ".config" / "secrets" / "openrouter.env",
+        ),
+    },
+    "kimi": {
+        "required": ("OPENROUTER_API_KEY",),
+        "secret_paths": (pathlib.Path.home() / ".config" / "secrets" / "openrouter.env",),
+    },
+}
+
+PROVIDER_AGENT: dict[str, str] = {
+    route["provider"]: route["agent"]
+    for routes in TASK_PROVIDER_MATRIX.values()
+    for route in routes
+}
+
+PROVIDER_DEFAULT_MODEL: dict[str, str] = {
+    route["provider"]: route["model"]
+    for routes in TASK_PROVIDER_MATRIX.values()
+    for route in routes
+}
+
+
+def normalize_task_type(task_type: str) -> str:
+    """Return the canonical matrix task type, falling back to refactor/codex."""
+    key = str(task_type or "").strip().lower().replace("-", "_")
+    return TASK_PROVIDER_ALIASES.get(key, key if key in TASK_PROVIDER_MATRIX else "refactor")
+
+
+def normalize_provider(provider: str) -> str:
+    """Normalize a provider override or raise ValueError for unsupported input."""
+    key = str(provider or "").strip().lower().replace("_", "-")
+    if not key:
+        raise ValueError("provider override is empty")
+    canonical = PROVIDER_ALIASES.get(key)
+    if not canonical:
+        supported = ", ".join(sorted(PROVIDER_AGENT))
+        raise ValueError(f"unsupported provider {provider!r}; supported providers: {supported}")
+    return canonical
+
+
+def provider_backend_for_provider(provider: str) -> dict[str, Any]:
+    """Return static REST backend metadata for a registered provider."""
+    canonical = normalize_provider(provider)
+    backend = PROVIDER_BACKENDS.get(canonical)
+    if not backend:
+        raise ValueError(f"provider {provider!r} has no direct backend registration")
+    return dict(backend, provider=canonical)
+
+
+def _read_secret_env_file(path: pathlib.Path) -> dict[str, str]:
+    """Parse KEY=value env files without logging or exposing values."""
+    try:
+        if not path.is_file():
+            return {}
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return {}
+    values: dict[str, str] = {}
+    for raw in lines:
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[len("export "):].strip()
+        if "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        key = key.strip()
+        value = value.strip().strip('"').strip("'")
+        if key and value:
+            values[key] = value
+    return values
+
+
+def _credential_keys(spec: dict[str, Any]) -> set[str]:
+    keys = set(str(k) for k in spec.get("required", ()))
+    for group in spec.get("any_of", ()):
+        keys.update(str(k) for k in group)
+    return keys
+
+
+def provider_credential_values(provider: str) -> dict[str, str]:
+    """Read provider credentials from env first, then configured secret files."""
+    canonical = normalize_provider(provider)
+    spec = PROVIDER_CREDENTIALS.get(canonical)
+    if not spec:
+        return {}
+    file_values: dict[str, str] = {}
+    for raw_path in spec.get("secret_paths", ()):
+        file_values.update(_read_secret_env_file(pathlib.Path(raw_path).expanduser()))
+
+    values: dict[str, str] = {}
+    for key in sorted(_credential_keys(spec)):
+        value = os.environ.get(key, "").strip() or file_values.get(key, "").strip()
+        if value:
+            values[key] = value
+    return values
+
+
+def provider_credentials_available(provider: str) -> bool:
+    """Return whether a provider has enough credentials for direct dispatch."""
+    canonical = normalize_provider(provider)
+    spec = PROVIDER_CREDENTIALS.get(canonical)
+    if not spec:
+        return True
+    values = provider_credential_values(canonical)
+    required = tuple(str(k) for k in spec.get("required", ()))
+    if required:
+        return all(bool(values.get(key)) for key in required)
+    groups = spec.get("any_of", ())
+    if groups:
+        return any(all(bool(values.get(str(key))) for key in group) for group in groups)
+    return True
+
+
+def provider_route_for_provider(provider: str, *, model: str = "") -> dict[str, str]:
+    """Build a provider route from an explicit CLI override."""
+    canonical = normalize_provider(provider)
+    return {
+        "provider": canonical,
+        "model": model or PROVIDER_DEFAULT_MODEL.get(canonical, ""),
+        "agent": PROVIDER_AGENT.get(canonical, canonical),
+        "source": "provider-override",
+    }
+
+
+def provider_matrix_for_task(
+    task_type: str,
+    *,
+    require_credentials: bool = False,
+) -> list[dict[str, str]]:
+    """Return ordered provider routes for a task type."""
+    canonical = normalize_task_type(task_type)
+    routes = [dict(route, source="task-matrix") for route in TASK_PROVIDER_MATRIX[canonical]]
+    if require_credentials:
+        available = [
+            route for route in routes
+            if provider_credentials_available(route["provider"])
+        ]
+        if available:
+            return available
+    return routes
+
+
+def provider_route_for_task(
+    task_type: str,
+    *,
+    require_credentials: bool = False,
+) -> dict[str, str]:
+    """Return the primary provider route for a task type."""
+    return provider_matrix_for_task(
+        task_type,
+        require_credentials=require_credentials,
+    )[0]
+
+
+# ---------------------------------------------------------------------------
+# RuAPI mirror fallback (#2251)
+#
+# Primary: ruapi (api.stepanovikov.uno)
+# Secondary: ruapi-shop (ruapi.shop) — same ANTHROPIC_AUTH_TOKEN, same models
+#
+# Callers that opt into fallback should use ``dispatch_ruapi_with_fallback``.
+# Existing single-endpoint clients are unaffected — primary behaviour stays
+# identical when the fallback path is not invoked.
+# ---------------------------------------------------------------------------
+
+RUAPI_MIRRORS: tuple[str, ...] = ("ruapi", "ruapi-shop")
+
+# HTTP statuses that should trigger a fallback to the next mirror.
+# 5xx = upstream/server error. 408/429 = transient retry candidates.
+RUAPI_RETRY_STATUSES: frozenset[int] = frozenset({408, 429, 500, 502, 503, 504})
+
+
+def _load_provider_registry_endpoints() -> dict[str, str]:
+    """Read provider-registry.json and return {provider_id: endpoint}.
+
+    stdlib-only — no jsonschema dep. Used for fallback dispatch so the
+    endpoints stay aligned with the canonical registry without duplication.
+    """
+    registry_path = (
+        pathlib.Path(__file__).resolve().parent.parent
+        / "ai" / "meta" / "manifest" / "provider-registry.json"
+    )
+    try:
+        data = json.loads(registry_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    providers = data.get("providers") or {}
+    return {
+        pid: spec.get("endpoint", "")
+        for pid, spec in providers.items()
+        if isinstance(spec, dict) and spec.get("endpoint")
+    }
+
+
+def ruapi_mirror_endpoints() -> list[tuple[str, str]]:
+    """Return ordered (provider_id, endpoint) tuples for the RuAPI mirror chain.
+
+    Order: primary first (ruapi), then secondary (ruapi-shop). Empty endpoints
+    are dropped silently — callers see only mirrors that the registry knows
+    about.
+    """
+    endpoints = _load_provider_registry_endpoints()
+    chain: list[tuple[str, str]] = []
+    for pid in RUAPI_MIRRORS:
+        endpoint = endpoints.get(pid, "").strip()
+        if endpoint:
+            chain.append((pid, endpoint))
+    return chain
+
+
+def dispatch_ruapi_with_fallback(
+    payload: dict,
+    *,
+    auth_token: str,
+    timeout: float = 30.0,
+    transport: Any = None,
+    extra_headers: dict[str, str] | None = None,
+) -> dict:
+    """Dispatch a chat-completions request through the RuAPI mirror chain.
+
+    Tries primary (ruapi) first; on 5xx / 408 / 429 / timeout / connection
+    error, falls back to ruapi-shop. Both fail → raises the last error.
+
+    Args:
+        payload: OpenAI-compat chat.completions request body (already JSON-able).
+        auth_token: ANTHROPIC_AUTH_TOKEN — sent as ``Authorization: Bearer ...``.
+        timeout: Per-attempt timeout in seconds.
+        transport: Optional callable for tests:
+            ``transport(endpoint, headers, body, timeout) -> (status, body_text)``
+            Defaults to a stdlib urllib-based transport.
+        extra_headers: Optional headers merged on top of the default UA + auth.
+
+    Returns:
+        Parsed JSON response body from the first mirror that returns a 2xx.
+
+    Raises:
+        RuntimeError: if every mirror fails. The message lists each mirror's
+            failure mode in attempt order so logs preserve the trace.
+    """
+    chain = ruapi_mirror_endpoints()
+    if not chain:
+        raise RuntimeError("ruapi fallback: no mirrors configured in provider-registry.json")
+
+    headers = {
+        "Content-Type": "application/json",
+        "User-Agent": "curl/8.5.0",
+        "Authorization": f"Bearer {auth_token}",
+    }
+    if extra_headers:
+        headers.update(extra_headers)
+
+    body_bytes = json.dumps(payload).encode("utf-8")
+    transport_fn = transport or _default_ruapi_transport
+
+    failures: list[str] = []
+    for provider_id, endpoint in chain:
+        try:
+            status, response_text = transport_fn(endpoint, headers, body_bytes, timeout)
+        except Exception as exc:  # noqa: BLE001 — mirror fallback: network/timeout/etc → try next mirror
+            failures.append(f"{provider_id}: {type(exc).__name__}: {exc}")
+            log.warning("ruapi mirror %s failed (%s); falling back", provider_id, exc)
+            continue
+
+        if 200 <= status < 300:
+            try:
+                return json.loads(response_text)
+            except json.JSONDecodeError as exc:
+                failures.append(f"{provider_id}: invalid JSON ({exc})")
+                log.warning("ruapi mirror %s returned non-JSON; falling back", provider_id)
+                continue
+
+        if status in RUAPI_RETRY_STATUSES:
+            failures.append(f"{provider_id}: HTTP {status}")
+            log.warning("ruapi mirror %s returned HTTP %s; falling back", provider_id, status)
+            continue
+
+        # Non-retryable error (e.g. 4xx auth/payload). Surface immediately —
+        # falling back would not help since both mirrors share the same key.
+        failures.append(f"{provider_id}: HTTP {status} (non-retryable)")
+        raise RuntimeError(
+            f"ruapi dispatch failed (non-retryable): {failures[-1]}; body={response_text[:200]!r}"
+        )
+
+    raise RuntimeError(
+        "ruapi dispatch failed across all mirrors: " + "; ".join(failures)
+    )
+
+
+def _default_ruapi_transport(
+    endpoint: str,
+    headers: dict[str, str],
+    body: bytes,
+    timeout: float,
+) -> tuple[int, str]:
+    """Default urllib-based transport for ruapi fallback.
+
+    Returns (status_code, response_text). Raises on connection-level errors
+    (timeouts, DNS, TLS) — caller treats those as a mirror miss.
+    """
+    import urllib.error
+    import urllib.request
+
+    request = urllib.request.Request(
+        endpoint, data=body, headers=headers, method="POST",
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            text = response.read().decode("utf-8", errors="replace")
+            return response.status, text
+    except urllib.error.HTTPError as exc:
+        # HTTPError is also a Response — preserve status + body so caller can
+        # decide whether to fall back (5xx) or surface (4xx).
+        body_text = ""
+        try:
+            body_text = exc.read().decode("utf-8", errors="replace")
+        except Exception:  # noqa: BLE001 — best-effort HTTP body capture; pragma: no cover
+            pass
+        return exc.code, body_text
+
+
+# Minimum events per model to be considered
+MIN_EVENTS = 3
+
+# Quality grade thresholds (used for display)
+QUALITY_GRADES = [
+    (90, "A"),  (80, "B+"), (70, "B"), (60, "C+"),
+    (50, "C"),  (40, "D"),  (0, "F"),
+]
+
+
+def quality_grade(score: float) -> str:
+    """Convert numeric quality score to letter grade."""
+    for threshold, grade in QUALITY_GRADES:
+        if score >= threshold:
+            return grade
+    return "F"
+
+
+# ---------------------------------------------------------------------------
+# Percentile helper (from cost_predictor, duplicated for independence)
+# ---------------------------------------------------------------------------
+
+def _percentile(sorted_values: list[float], p: float) -> float:
+    if not sorted_values:
+        return 0.0
+    if len(sorted_values) == 1:
+        return sorted_values[0]
+    k = (len(sorted_values) - 1) * p
+    f = math.floor(k)
+    c = min(math.ceil(k), len(sorted_values) - 1)
+    if f == c:
+        return sorted_values[f]
+    return sorted_values[f] + (sorted_values[c] - sorted_values[f]) * (k - f)
+
+
+# ---------------------------------------------------------------------------
+# Data aggregation
+# ---------------------------------------------------------------------------
+
+def aggregate_model_stats(
+    target_path: pathlib.Path | str,
+    task_type: str = "",
+    period: str = "30d",
+) -> dict[str, dict]:
+    """Aggregate per-model stats from experience events.
+
+    Returns dict keyed by "agent/model" with stats for each combination
+    that has >= MIN_EVENTS events.
+    """
+    sys.path.insert(0, str(pathlib.Path(__file__).parent))
+    import experience_pipeline as ep
+
+    target = pathlib.Path(target_path).resolve()
+    events = ep.load_events(target, since=period, limit=5000, include_archive=False)
+
+    # Filter to task events with cost
+    task_events = [
+        e for e in events
+        if str(e.get("event_type", "")).startswith("task_")
+    ]
+
+    # Optional task_type filter
+    if task_type:
+        task_events = [
+            e for e in task_events
+            if (e.get("task") or {}).get("task_type") == task_type
+        ]
+
+    # Group by agent/model
+    groups: dict[str, list[dict]] = {}
+    for e in task_events:
+        agent = e.get("agent", "unknown")
+        model = e.get("model", "unknown")
+        key = f"{agent}/{model}"
+        groups.setdefault(key, []).append(e)
+
+    result: dict[str, dict] = {}
+    for key, events_list in groups.items():
+        if len(events_list) < MIN_EVENTS:
+            continue
+
+        costs = sorted(
+            float((e.get("task") or {}).get("cost_usd", 0))
+            for e in events_list
+        )
+        elapsed_list = sorted(
+            float((e.get("task") or {}).get("elapsed_seconds", 0))
+            for e in events_list
+        )
+        successes = sum(
+            1 for e in events_list
+            if (e.get("task") or {}).get("result") in ("success", "partial")
+        )
+
+        # Quality: use quality block if available, else estimate from success
+        quality_scores = []
+        for e in events_list:
+            q = e.get("quality", {})
+            if q:
+                # Simple quality metric: count True values in quality block
+                checks = [q.get("lint_clean"), q.get("no_secrets"),
+                          q.get("commit_message_valid"), q.get("acceptance_criteria_met")]
+                passed = sum(1 for c in checks if c is True)
+                total = sum(1 for c in checks if c is not None)
+                if total > 0:
+                    quality_scores.append(passed / total * 100)
+
+        quality_avg = (
+            round(sum(quality_scores) / len(quality_scores), 1)
+            if quality_scores
+            else round(successes / len(events_list) * 80, 1)  # fallback: success → ~80 max
+        )
+
+        result[key] = {
+            "events": len(events_list),
+            "success_rate": round(successes / len(events_list), 2),
+            "quality_avg": quality_avg,
+            "cost_median": round(_percentile(costs, 0.5), 4),
+            "cost_p25": round(_percentile(costs, 0.25), 4),
+            "cost_p75": round(_percentile(costs, 0.75), 4),
+            "time_median": round(_percentile(elapsed_list, 0.5), 0),
+            "time_p25": round(_percentile(elapsed_list, 0.25), 0),
+            "time_p75": round(_percentile(elapsed_list, 0.75), 0),
+        }
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Scoring
+# ---------------------------------------------------------------------------
+
+def compute_model_score(stats: dict, weights: dict, pool_max: dict) -> float:
+    """Compute composite score for a model.
+
+    score = (quality_avg/100 * quality_weight) +
+            (success_rate * success_weight) +
+            ((1 - normalized_cost) * cost_weight) +
+            ((1 - normalized_time) * speed_weight)
+
+    Higher = better. Range: 0.0–1.0
+    """
+    quality_norm = stats.get("quality_avg", 0) / 100.0
+    success = stats.get("success_rate", 0)
+
+    max_cost = pool_max.get("max_cost", 1.0)
+    max_time = pool_max.get("max_time", 1.0)
+
+    cost_norm = stats.get("cost_median", 0) / max_cost if max_cost > 0 else 0
+    time_norm = stats.get("time_median", 0) / max_time if max_time > 0 else 0
+
+    score = (
+        quality_norm * weights.get("quality", 0.3) +
+        success * weights.get("success", 0.3) +
+        (1.0 - cost_norm) * weights.get("cost", 0.2) +
+        (1.0 - time_norm) * weights.get("speed", 0.15)
+    )
+    return round(min(1.0, max(0.0, score)), 3)
+
+
+# ---------------------------------------------------------------------------
+# Constraints
+# ---------------------------------------------------------------------------
+
+def apply_constraints(
+    candidates: dict[str, dict],
+    constraints: dict | None,
+) -> tuple[dict[str, dict], list[dict]]:
+    """Filter models that don't meet constraints.
+
+    Returns (filtered_candidates, filtered_out_list).
+    """
+    if not constraints:
+        return candidates, []
+
+    filtered_out: list[dict] = []
+    result: dict[str, dict] = {}
+
+    max_cost = constraints.get("max_cost")
+    min_quality = constraints.get("min_quality")
+    max_time = constraints.get("max_time")
+
+    for key, stats in candidates.items():
+        reasons = []
+        if max_cost is not None and stats.get("cost_median", 0) > max_cost:
+            reasons.append(f"cost ${stats['cost_median']:.4f} > max ${max_cost}")
+        if min_quality is not None and stats.get("quality_avg", 0) < min_quality:
+            reasons.append(f"quality {stats['quality_avg']} < min {min_quality}")
+        if max_time is not None and stats.get("time_median", 0) > max_time:
+            reasons.append(f"time {stats['time_median']}s > max {max_time}s")
+
+        if reasons:
+            filtered_out.append({"model": key, "reasons": reasons})
+        else:
+            result[key] = stats
+
+    return result, filtered_out
+
+
+# ---------------------------------------------------------------------------
+# Recommendation
+# ---------------------------------------------------------------------------
+
+@dataclasses.dataclass
+class ModelRecommendation:
+    """Structured model recommendation result."""
+    recommended: dict | None
+    alternatives: list[dict]
+    ranking_factors: dict
+    constraints_applied: dict
+    task_type: str
+    data_period: str
+    total_events_analyzed: int
+    source: str = "experience"  # "experience" (default) | "task-matrix"
+
+
+def recommend_model(
+    target_path: pathlib.Path | str,
+    task_type: str,
+    goal: str = "",
+    constraints: dict | None = None,
+    period: str = "30d",
+) -> ModelRecommendation:
+    """Recommend best model for a task type based on experience data.
+
+    Args:
+        target_path: Project root.
+        task_type: One of feat, fix, refactor, test, docs.
+        goal: Optional goal text for context.
+        constraints: Optional {max_cost, min_quality, max_time}.
+        period: Lookback period (default 30d).
+
+    Returns ModelRecommendation with top pick and alternatives.
+    """
+    target = pathlib.Path(target_path).resolve()
+
+    # Infer task type from goal if needed
+    if not task_type and goal:
+        try:
+            import cost_predictor
+            task_type = cost_predictor.infer_task_type(goal)
+        except ImportError:
+            # Fallback: basic keyword inference
+            gl = goal.lower()
+            if any(k in gl for k in ("fix", "bug", "patch")):
+                task_type = "fix"
+            elif any(k in gl for k in ("refactor", "restructure")):
+                task_type = "refactor"
+            elif any(k in gl for k in ("test", "spec")):
+                task_type = "test"
+            elif any(k in gl for k in ("doc", "readme")):
+                task_type = "docs"
+            else:
+                task_type = "feat"
+    if not task_type:
+        task_type = "feat"
+
+    weights = TASK_WEIGHTS.get(task_type, DEFAULT_WEIGHTS)
+
+    # Aggregate stats
+    all_stats = aggregate_model_stats(target, task_type, period)
+
+    if not all_stats:
+        # Try without task_type filter
+        all_stats = aggregate_model_stats(target, "", period)
+
+    total_events = sum(s["events"] for s in all_stats.values())
+
+    # Apply constraints
+    candidates, filtered_out = apply_constraints(all_stats, constraints)
+
+    # If all filtered out, fall back to unconstrained
+    if not candidates and all_stats:
+        candidates = all_stats
+        filtered_out = []  # reset — we're ignoring constraints
+
+    if not candidates:
+        fallback_list = provider_matrix_for_task(task_type)
+        if fallback_list:
+            primary = fallback_list[0]
+            provider = primary["provider"]
+            model = primary["model"]
+            agent = primary["agent"]
+            recommended_static = {
+                "agent": agent,
+                "model": model,
+                "reason": f"Cold-start provider matrix route for {task_type} tasks (no experience data yet).",
+                "expected_cost": None,
+                "expected_quality": None,
+                "expected_time": None,
+                "success_rate": None,
+                "confidence": "task-matrix",
+                "sample_size": 0,
+                "score": 0.0,
+                "provider": provider,
+                "tier": primary.get("tier", ""),
+                "effort": primary.get("effort", ""),
+                "billing_class": primary.get("billing_class", ""),
+            }
+            return ModelRecommendation(
+                recommended=recommended_static,
+                alternatives=[
+                    {
+                        "agent": route["agent"],
+                        "model": route["model"],
+                        "reason": f"Cold-start provider matrix route for {task_type} tasks.",
+                        "expected_cost": None,
+                        "expected_quality": None,
+                        "expected_time": None,
+                        "success_rate": None,
+                        "tradeoff": "matrix-fallback",
+                        "score": 0.0,
+                        "provider": route["provider"],
+                        "tier": route.get("tier", ""),
+                        "effort": route.get("effort", ""),
+                        "billing_class": route.get("billing_class", ""),
+                    }
+                    for route in fallback_list[1:]
+                ],
+                ranking_factors=weights,
+                constraints_applied={
+                    "max_cost": (constraints or {}).get("max_cost"),
+                    "min_quality": (constraints or {}).get("min_quality"),
+                    "max_time": (constraints or {}).get("max_time"),
+                    "filtered_out": filtered_out,
+                },
+                task_type=task_type,
+                data_period=period,
+                total_events_analyzed=total_events,
+                source="task-matrix",
+            )
+        # If even the fallback table has no entry — keep the original None return
+        return ModelRecommendation(
+            recommended=None,
+            alternatives=[],
+            ranking_factors=weights,
+            constraints_applied={
+                "max_cost": (constraints or {}).get("max_cost"),
+                "min_quality": (constraints or {}).get("min_quality"),
+                "max_time": (constraints or {}).get("max_time"),
+                "filtered_out": filtered_out,
+            },
+            task_type=task_type,
+            data_period=period,
+            total_events_analyzed=total_events,
+            source="experience",
+        )
+
+    # Compute pool maximums for normalization
+    pool_max = {
+        "max_cost": max(s["cost_median"] for s in candidates.values()) or 0.01,
+        "max_time": max(s["time_median"] for s in candidates.values()) or 1.0,
+    }
+
+    # Score and rank
+    scored: list[tuple[str, dict, float]] = []
+    for key, stats in candidates.items():
+        score = compute_model_score(stats, weights, pool_max)
+        scored.append((key, stats, score))
+
+    scored.sort(key=lambda x: -x[2])
+
+    # Build recommendation
+    top_key, top_stats, top_score = scored[0]
+    agent, model = top_key.split("/", 1) if "/" in top_key else (top_key, "default")
+
+    recommended = {
+        "agent": agent,
+        "model": model,
+        "reason": _generate_reason(top_stats, task_type, is_top=True),
+        "expected_cost": top_stats["cost_median"],
+        "expected_quality": top_stats["quality_avg"],
+        "expected_time": top_stats["time_median"],
+        "success_rate": top_stats["success_rate"],
+        "confidence": _recommendation_confidence(top_stats["events"]),
+        "sample_size": top_stats["events"],
+        "score": top_score,
+    }
+
+    alternatives = []
+    for key, stats, score in scored[1:4]:  # top 3 alternatives
+        a_agent, a_model = key.split("/", 1) if "/" in key else (key, "default")
+        cost_diff = (
+            round((1 - stats["cost_median"] / top_stats["cost_median"]) * 100)
+            if top_stats["cost_median"] > 0 else 0
+        )
+        tradeoff = "cost_saving" if cost_diff > 20 else "similar"
+        if stats["quality_avg"] > top_stats["quality_avg"]:
+            tradeoff = "higher_quality"
+
+        alternatives.append({
+            "agent": a_agent,
+            "model": a_model,
+            "reason": _generate_reason(stats, task_type, is_top=False, cost_diff=cost_diff),
+            "expected_cost": stats["cost_median"],
+            "expected_quality": stats["quality_avg"],
+            "expected_time": stats["time_median"],
+            "success_rate": stats["success_rate"],
+            "tradeoff": tradeoff,
+            "score": score,
+        })
+
+    return ModelRecommendation(
+        recommended=recommended,
+        alternatives=alternatives,
+        ranking_factors=weights,
+        constraints_applied={
+            "max_cost": (constraints or {}).get("max_cost"),
+            "min_quality": (constraints or {}).get("min_quality"),
+            "max_time": (constraints or {}).get("max_time"),
+            "filtered_out": filtered_out,
+        },
+        task_type=task_type,
+        data_period=period,
+        total_events_analyzed=total_events,
+    )
+
+
+def _recommendation_confidence(sample_size: int) -> str:
+    if sample_size >= 20:
+        return "high"
+    if sample_size >= 5:
+        return "medium"
+    return "low"
+
+
+def _generate_reason(
+    stats: dict, task_type: str, *, is_top: bool, cost_diff: int = 0,
+) -> str:
+    """Generate a human-readable reason for the recommendation."""
+    grade = quality_grade(stats["quality_avg"])
+    sr = f"{int(stats['success_rate'] * 100)}%"
+
+    if is_top:
+        if task_type == "refactor":
+            return f"Highest quality for refactor tasks ({stats['quality_avg']:.0f} avg, {grade} grade)"
+        if task_type == "fix":
+            return f"Best success rate for fixes ({sr} success, {grade} quality)"
+        if task_type in ("test", "docs"):
+            return f"Best value for {task_type} tasks ({sr} success, ${stats['cost_median']:.2f} avg)"
+        return f"Best overall score ({grade} quality, {sr} success)"
+
+    if cost_diff > 30:
+        return f"{cost_diff}% cheaper, {sr} success rate"
+    if stats["success_rate"] > 0.85:
+        return f"Similar success ({sr}), ${stats['cost_median']:.4f} median cost"
+    return f"{grade} quality, {sr} success, ${stats['cost_median']:.4f} cost"
+
+
+# ---------------------------------------------------------------------------
+# Serialization
+# ---------------------------------------------------------------------------
+
+def recommendation_to_dict(rec: ModelRecommendation) -> dict:
+    """Convert to JSON-serializable dict."""
+    return {
+        "recommended": rec.recommended,
+        "alternatives": rec.alternatives,
+        "ranking_factors": rec.ranking_factors,
+        "constraints_applied": rec.constraints_applied,
+        "task_type": rec.task_type,
+        "data_period": rec.data_period,
+        "total_events_analyzed": rec.total_events_analyzed,
+        "source": rec.source,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Benchmark table
+# ---------------------------------------------------------------------------
+
+def get_benchmark(
+    target_path: pathlib.Path | str,
+    period: str = "30d",
+) -> dict:
+    """Get benchmark data: all models ranked by composite score.
+
+    Returns {models: [{key, events, success_rate, quality_avg, cost_median, time_median, score}],
+             best_for: {task_type: model_key}}.
+    """
+    target = pathlib.Path(target_path).resolve()
+    all_stats = aggregate_model_stats(target, "", period)
+
+    if not all_stats:
+        return {"models": [], "best_for": {}, "period": period}
+
+    pool_max = {
+        "max_cost": max(s["cost_median"] for s in all_stats.values()) or 0.01,
+        "max_time": max(s["time_median"] for s in all_stats.values()) or 1.0,
+    }
+
+    # Default weights for overall ranking
+    models = []
+    for key, stats in all_stats.items():
+        score = compute_model_score(stats, DEFAULT_WEIGHTS, pool_max)
+        models.append({
+            "key": key,
+            "events": stats["events"],
+            "success_rate": stats["success_rate"],
+            "quality_avg": stats["quality_avg"],
+            "quality_grade": quality_grade(stats["quality_avg"]),
+            "cost_median": stats["cost_median"],
+            "time_median": stats["time_median"],
+            "score": score,
+        })
+
+    models.sort(key=lambda x: -x["score"])
+
+    # Best for each task type
+    best_for = {}
+    for tt in TASK_WEIGHTS:
+        tt_stats = aggregate_model_stats(target, tt, period)
+        if not tt_stats:
+            continue
+        tt_pool = {
+            "max_cost": max(s["cost_median"] for s in tt_stats.values()) or 0.01,
+            "max_time": max(s["time_median"] for s in tt_stats.values()) or 1.0,
+        }
+        tt_weights = TASK_WEIGHTS[tt]
+        best_key = max(
+            tt_stats.keys(),
+            key=lambda k: compute_model_score(tt_stats[k], tt_weights, tt_pool),
+        )
+        best_for[tt] = best_key
+
+    return {"models": models, "best_for": best_for, "period": period}
+
+
+# ---------------------------------------------------------------------------
+# Agent Outcome Ledger — pick best agent for THIS repo's history (#483 follow-up)
+# ---------------------------------------------------------------------------
+
+
+def pick_best_agent_for_repo(
+    target_path: pathlib.Path | str,
+    task_type: str = "",
+    *,
+    top_n: int = 3,
+) -> list[tuple[str, float, int]]:
+    """Return top-N (agent, weighted_score, sample_count) for this repo.
+
+    Reads the outcome ledger written by swarm.cmd_done via task_outcomes.
+    Returns empty list on cold start (<5 records) — caller should fall back
+    to static TIER_MODELS.
+
+    See ai/docs/plan-30d-2026-04-17.md §2.1 for rationale.
+    """
+    try:
+        from . import task_outcomes
+    except ImportError:
+        import task_outcomes  # type: ignore
+    target = pathlib.Path(target_path).resolve()
+    return task_outcomes.pick_best_agent_for_repo(target, task_type, top_n=top_n)
+
+
+def _load_task_outcomes_module():
+    try:
+        from . import task_outcomes
+    except ImportError:
+        import task_outcomes  # type: ignore
+    return task_outcomes
+
+
+def ledger_recommendation(
+    target_path: pathlib.Path | str,
+    task_type: str = "",
+    period: str = "30d",
+    *,
+    top_n: int = 3,
+) -> dict:
+    """Build the combined ledger + static recommendation payload for the CLI.
+
+    Schema (stable — consumed by `0dai models recommend` and /models dashboard):
+        {
+          ledger_recommendations: [{agent, avg_score, tasks_count, avg_cost_per_task}],
+          static_recommendations: [{agent, model, score, expected_cost,
+                                    expected_quality, success_rate, reason, ...}],
+          ledger_size: int,
+          cold_start: bool,
+          task_type: str,
+          cold_start_threshold: int,
+        }
+    """
+    task_outcomes = _load_task_outcomes_module()
+    target = pathlib.Path(target_path).resolve()
+
+    summary = task_outcomes.summarize_ledger(target)
+    ranked = task_outcomes.pick_best_agent_for_repo(target, task_type, top_n=top_n)
+
+    ledger_recs: list[dict] = []
+    for agent, avg_score, tasks_count in ranked:
+        bucket = (summary.get("agents") or {}).get(agent) or {}
+        ledger_recs.append({
+            "agent": agent,
+            "avg_score": float(avg_score),
+            "tasks_count": int(tasks_count),
+            "avg_cost_per_task": round(float(bucket.get("avg_cost_usd") or 0.0), 4),
+        })
+
+    rec = recommend_model(target, task_type, period=period)
+    static_recs: list[dict] = []
+    if rec.recommended:
+        r = rec.recommended
+        static_recs.append({
+            "agent": r["agent"],
+            "model": r["model"],
+            "score": r["score"],
+            "expected_cost": r["expected_cost"],
+            "expected_quality": r["expected_quality"],
+            "success_rate": r["success_rate"],
+            "reason": r["reason"],
+            "confidence": r["confidence"],
+            "sample_size": r["sample_size"],
+        })
+        for alt in rec.alternatives[: max(0, top_n - 1)]:
+            static_recs.append({
+                "agent": alt["agent"],
+                "model": alt["model"],
+                "score": alt["score"],
+                "expected_cost": alt["expected_cost"],
+                "expected_quality": alt["expected_quality"],
+                "success_rate": alt["success_rate"],
+                "reason": alt["reason"],
+                "tradeoff": alt.get("tradeoff"),
+            })
+
+    return {
+        "ledger_recommendations": ledger_recs,
+        "static_recommendations": static_recs,
+        "ledger_size": int(summary.get("total_tasks") or 0),
+        "cold_start": bool(summary.get("cold_start", True)),
+        "cold_start_threshold": task_outcomes._COLD_START_THRESHOLD,
+        "task_type": task_type or rec.task_type,
+        "data_period": period,
+    }
+
+
+def _render_ledger_recommendation(data: dict) -> str:
+    """Human-readable rendering for the CLI (no colour — stays TTY-neutral)."""
+    lines: list[str] = []
+    task_type = data.get("task_type") or "feat"
+    lines.append(f"\n  Model recommendation for {task_type} tasks:")
+
+    if data.get("cold_start"):
+        n = data.get("ledger_size", 0)
+        thr = data.get("cold_start_threshold", 5)
+        lines.append(
+            f"\n  \u23f3 ledger warming up ({n}/{thr} records) — "
+            f"showing provider matrix rankings only."
+        )
+    else:
+        lines.append("\n  From your repo's history:")
+        ledger = data.get("ledger_recommendations") or []
+        if not ledger:
+            lines.append("    (no ledger matches for this task type)")
+        else:
+            medals = ["\U0001f947", "\U0001f948", "\U0001f949"]
+            for i, item in enumerate(ledger):
+                medal = medals[i] if i < len(medals) else f"  {i + 1}."
+                lines.append(
+                    f"    {medal} {item['agent']}  "
+                    f"— avg_score {item['avg_score']:.2f}  "
+                    f"({item['tasks_count']} tasks, "
+                    f"${item['avg_cost_per_task']:.4f}/task)"
+                )
+
+    static = data.get("static_recommendations") or []
+    lines.append("\n  Provider matrix rankings:")
+    if not static:
+        lines.append("    (no experience-event recommendation — run swarm tasks to build history)")
+    else:
+        medals = ["\U0001f947", "\U0001f948", "\U0001f949"]
+        for i, item in enumerate(static):
+            medal = medals[i] if i < len(medals) else f"  {i + 1}."
+            eq = item.get("expected_quality") or 0
+            grade = quality_grade(eq)
+            sr = int((item.get("success_rate") or 0.0) * 100)
+            ec = item.get("expected_cost") or 0.0
+            lines.append(
+                f"    {medal} {item['agent']}/{item['model']}  "
+                f"— Quality: {eq:.0f} ({grade}) | "
+                f"Success: {sr}% | Cost: ${ec:.4f}"
+            )
+            reason = item.get("reason")
+            if reason:
+                lines.append(f"        \"{reason}\"")
+
+    lines.append("")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# CLI entry point
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    import argparse
+
+    sys.path.insert(0, str(pathlib.Path(__file__).parent))
+
+    parser = argparse.ArgumentParser(description="Model routing recommendations")
+    sub = parser.add_subparsers(dest="command")
+
+    rec_p = sub.add_parser("recommend")
+    rec_p.add_argument("--target", default=".")
+    rec_p.add_argument("--task", default="")
+    rec_p.add_argument("--goal", default="")
+    rec_p.add_argument("--max-cost", type=float, default=None)
+    rec_p.add_argument("--min-quality", type=float, default=None)
+    rec_p.add_argument("--max-time", type=float, default=None)
+    rec_p.add_argument("--period", default="30d")
+    rec_p.add_argument("--json", action="store_true")
+
+    bench_p = sub.add_parser("benchmark")
+    bench_p.add_argument("--target", default=".")
+    bench_p.add_argument("--period", default="30d")
+    bench_p.add_argument("--json", action="store_true")
+
+    lg_p = sub.add_parser(
+        "ledger-recommend",
+        help="Recommend agents using the per-repo outcome ledger + provider matrix.",
+    )
+    lg_p.add_argument("--target", default=".")
+    lg_p.add_argument("--task", default="")
+    lg_p.add_argument("--period", default="30d")
+    lg_p.add_argument("--top-n", type=int, default=3)
+    lg_p.add_argument("--json", action="store_true")
+
+    args = parser.parse_args()
+
+    if args.command == "recommend":
+        constraints = {}
+        if args.max_cost is not None:
+            constraints["max_cost"] = args.max_cost
+        if args.min_quality is not None:
+            constraints["min_quality"] = args.min_quality
+        if args.max_time is not None:
+            constraints["max_time"] = args.max_time
+
+        rec = recommend_model(
+            args.target, args.task, args.goal,
+            constraints or None, args.period,
+        )
+        if args.json:
+            print(json.dumps(recommendation_to_dict(rec), indent=2, ensure_ascii=False))
+        else:
+            d = recommendation_to_dict(rec)
+            print(f"\nRecommended for {d['task_type']} tasks:\n")
+            r = d["recommended"]
+            if r:
+                eq = r["expected_quality"] or 0
+                g = quality_grade(eq)
+                print(f"  \U0001f947 {r['agent']}/{r['model']}")
+                sr_pct = int((r["success_rate"] or 0.0) * 100)
+                ec = r["expected_cost"] or 0.0
+                et = r["expected_time"] or 0.0
+                print(f"     Quality: {eq:.0f} ({g}) | Success: {sr_pct}% | Cost: ${ec:.4f} | Time: {et:.0f}s")
+                print(f"     \"{r['reason']}\"")
+                for i, alt in enumerate(d["alternatives"], 2):
+                    medal = ["\U0001f948", "\U0001f949"][min(i - 2, 1)]
+                    aeq = alt["expected_quality"] or 0
+                    ag = quality_grade(aeq)
+                    print(f"\n  {medal} {alt['agent']}/{alt['model']}")
+                    asr = int((alt["success_rate"] or 0.0) * 100)
+                    aec = alt["expected_cost"] or 0.0
+                    aet = alt["expected_time"] or 0.0
+                    print(f"     Quality: {aeq:.0f} ({ag}) | Success: {asr}% | Cost: ${aec:.4f} | Time: {aet:.0f}s")
+                    print(f"     \"{alt['reason']}\"")
+                print(f"\n  Based on {d['total_events_analyzed']} events ({d['data_period']}). Confidence: {r['confidence']}.")
+            else:
+                print("  No recommendation available — not enough experience data.")
+                print("  Run some swarm tasks to build up history.")
+            print()
+
+    elif args.command == "ledger-recommend":
+        data = ledger_recommendation(
+            args.target, args.task, args.period, top_n=args.top_n,
+        )
+        if args.json:
+            print(json.dumps(data, indent=2, ensure_ascii=False))
+        else:
+            print(_render_ledger_recommendation(data))
+
+    elif args.command == "benchmark":
+        data = get_benchmark(args.target, args.period)
+        if args.json:
+            print(json.dumps(data, indent=2, ensure_ascii=False))
+        else:
+            models = data["models"]
+            if not models:
+                print("\n  No benchmark data — not enough experience events.\n")
+            else:
+                print(f"\n  Model benchmark (last {data['period']}):\n")
+                print(f"  {'Agent/Model':<25} {'Tasks':>5} {'Success':>8} {'Quality':>10} {'Avg Cost':>10} {'Avg Time':>10} {'Score':>6}")
+                print(f"  {'-'*76}")
+                for m in models:
+                    print(f"  {m['key']:<25} {m['events']:>5} {int(m['success_rate']*100):>7}% {m['quality_avg']:>6.0f} ({m['quality_grade']:<2}) ${m['cost_median']:>8.4f} {m['time_median']:>8.0f}s {m['score']:>6.3f}")
+                bf = data.get("best_for", {})
+                if bf:
+                    print("\n  Best for:")
+                    for tt, key in sorted(bf.items()):
+                        print(f"    {tt:<10} {key}")
+                print()
+    else:
+        parser.print_help()