Model Catalog (pick a model for a task, under a budget)

SpiderGate's catalog turns bare model specs into a rich, cited profile: spec + authored editorial + benchmarks + a live per-provider price/latency snapshot + reference links + an evals aggregate, every sourced field carrying provenance. On top of it sits a public model×task leaderboard and a per-model #7 evals aggregate — the shared prior a planner blends against its own experience.

    ┌── GET /catalog/leaderboard?task_type=coding   (PUBLIC — no PAT)
    │       models ranked by auto-eval score, each row: headline benchmark
    │       + cheapest live blended $ across providers
    │
your ──Bearer PAT──▶ GET /catalog/models?fields=capabilities,pricing,per_provider,evals
agent               │       enriched rows, narrowed to the sections you need
    │               ├── GET /catalog/models/{id}          full record for one
    │               └── GET /catalog/models/{id}/evals    the #7 prior (per task)
    │
    ▼  pick a row  ──▶  read its call_as  ──▶  use-the-gateway  chat(model: <call_as>)
          call_as is null  ──▶  the shared pool cannot serve that row now

All reads are LIST-ONLY — not metered, not billable (same class as listModels).

Approach

• "Best model for <task> under $X" — the headline job. Rank on the leaderboard for the task, then filter the returned rows by the blended price. → references/best-model-under-budget.md.
• Compare a shortlist in depth — pull the enriched catalog with fields= to narrow, or getModel one record: spec, capabilities, per-provider pricing, benchmarks, evals side by side. → references/enriched-catalog.md.
• Trust the eval prior — read the per-model #7 aggregate (auto rollups + human ratings) for a task before you rely on a model for it; a null score means "no contribution yet", not zero. → references/evals-as-prior.md.
• "Best model for a capability" (coding, vision, reasoning…) — a different axis from the eval prior: rank by the benchmark-derived per-category percentile. listCategories() to see the 9 categories + how many models each scores, then leaderboard(category=<key>, sort=score) to rank; read a specific model's own scores with listCatalog(fields=category_scores) / getModel(model_id) (it takes no fields and returns every section). Only ~19% of models are scored — an empty category_scores[] means "unscored", not "bad". → references/pick-by-category.md.
• Call the winner: send its call_as. Every catalog row carries call_as, the exact model string to pass to use-the-gateway's chat for that row right now, or null. If it is null, the shared pool cannot serve that row now; it does not cover your brand's own unshared keys. Do not send the row's id or model_id instead. You do not have to route through a task alias. → references/enriched-catalog.md.

Decision tree

The rules that trip agents up

• A row's id is a lookup key. For a Codex row the id and the model_id are both refused as model; the row is called as codex/<model_id>, and that is what its call_as holds while the gateway holds a pooled Codex seat.
• A filter does not make a row callable. configured_only=true selects on a stored is_configured flag, not on a live check, and it can return a row whose call_as is null. servable stays false for Codex. Decide on call_as.
• Leaderboard rows carry id and no call_as. Before you call a ranked model, read it with getModel(id) and send that record's call_as.
• call_as is read from one gateway process's key state on each request and can differ between two reads for a moment. Read it close to the call; do not cache it with the rest of the catalog.</HARD-GATE>

They are NOT interchangeable. A category score is a percentile (0–100), not a raw benchmark mean; read rank ÷ total for "rank/N", and a score's components[] is the WHY. Only ~19% of models are scored — treat an empty category_scores[] as "unscored", never "worst". Call listCategories() to get the valid category keys before ranking. </HARD-GATE>

Surfaces

• HTTP (this skill wraps it): GET /api/gate/v1/catalog/{models,models/{id},models/{id}/evals,leaderboard,categories}. Per-category ranking = GET /catalog/leaderboard?category=<key>&sort=score; each model's own scores = category_scores in the fields= child section on /catalog/models[/{id}]. The skill methods (listCategories, leaderboard with category) call these directly through the OPVS proxy — no client tool needed.
• CLI: spideriq gate catalog list|get|leaderboard|evals (client PAT; leaderboard public). ⚠ The CLI leaderboard is --task-type only — the per-category mode + /catalog/categories are NOT yet exposed as CLI commands (HTTP + this skill only, today).
• MCP: gate_catalog_list, gate_catalog_get, gate_leaderboard (task_type only), gate_catalog_model_evals (the @spideriq/mcp-gate slice). ⚠ There is no client MCP tool for the category read or the per-category leaderboard yet — the category surface reaches agents via THIS skill (HTTP proxy). A follow-up may add gate_catalog_categories + a category arg on gate_leaderboard.
• Admin (NOT this skill): editing the categories / scoring recipe is the @spideriq/admin-skills curate-categories skill (super_admin, X-Admin-Key).