[Deep-Sixed]

Summary

Phase 2 of Jev routing: native jev aliases. Cerberus asks Jev, through OpenRouter's Decisions API, which pool model should serve a request, then runs that model through its own failover loop. The pool may include local hosts, Cloudflare, OpenRouter, or any other registered provider.

CERBERUS  "what may run?"    registry policy → cost → health → cooldown → credential
JEV       "what should run?" one choice question over what survived
PROVIDER  "run it."          Cerberus's dispatch loop, chosen model first

cerberus/smart:
  mode: jev
  candidates:                       # configured order = the fallback order
    - { provider: thanatos,   credential: none,    model: gemma-4-12b }
    - { provider: openrouter, credential: primary, model: anthropic/claude-sonnet }
  jev:
    decider: { provider: openrouter, credential: primary }
    model: typesafe/jev-1.13        # pinned; bump deliberately after testing
    input: last_user_message        # | full_conversation | metadata
    max_input_chars: 4000
    timeout_seconds: 5
    allow_paid_pool: true

What Jev sees

• Candidates are the models that pass router/pool.py (the filter added in Deep-Sixed/Cerberus#28). Each distinct model is offered under an opaque id (m1, m2, …).
• Each model is described only by registry facts: model id, strength (new registry field, required for jev pool models), cost tier, context window, capabilities and description. Provider and credential names never leave.
• jev.input controls what request text is sent: the latest user message by default, the full conversation if opted in, or metadata only (no prompt text). Text is always truncated, and Jev always gets the request's shape: turns, size, tools, response format and requested output length.
• When only one model (or none) is left, no decision is requested, so no text leaves Cerberus.

What Jev can change

• Order only. The chosen model runs first. The rest of the cost-admitted pool follows in configured order.
• dispatch() takes a new DispatchPlan and runs it through the normal loop: health, cooldown and credential checks, 429 cooldowns, failover, streaming and telemetry.
• A plan that names a target the alias doesn't configure is refused.
• An answer that isn't exactly one of the offered ids is never acted on.

When Jev can't answer: configured order (your choice)

Any of these runs the request in configured order: missing backend or credential, the decider's provider marked down, timeout, transport or HTTP error, an unreadable response, or a missing or unknown choice. The reason is recorded. A decision outage never takes the alias down.

Telemetry and console

• Telemetry schema 7 adds a jev record: options offered, chosen / skipped / fallback, reason, choice, probability, decision latency, status and usage. It never includes request text.
• /admin/routes and the console report the pool's readiness and the decider's readiness separately.
• The control plane stores binding_type = 'jev' with pool members. No migration is needed.

Decisions API contract

Confirmed (from the material you sent):

• POST https://openrouter.ai/api/alpha/decisions with a bearer key
• a model / state / questions body
• choice / noul / score question types
• answers keyed by question id, plus usage
• model typesafe/jev-1.13

Not yet confirmed: the field names inside a single question and a single answer.

• The request uses the plainest form: {"id": "route", "type": "choice", "question": …, "options": [ids]}.
• The answer reader accepts choice / result / value / answer / selected, or the option with the highest probability.
• Whatever it reads must exactly match an id Cerberus offered. If the guess is wrong, requests run in configured order and telemetry says why; they never reach a model outside the pool.

Test plan

• ./scripts/ci.sh: ruff clean, 418 passed. New tests: 35 in tests/test_jev_dispatch.py and 7 jev cases in tests/test_schema.py.
• Mutation checks: accepting any answer, ignoring jev.input, and ignoring the choice each fail 3 tests.
• uv build --no-build-isolation; the wheel includes cerberus/jev.
• node --check src/cerberus/ui/static/app.js
• python scripts/check-public-history.py: 0 findings.
• Live probe against the Decisions API with a real key, to confirm the question and answer field names. If they differ, jev.reason will read http_error (request shape) or no_choice (answer shape), and the fix stays inside src/cerberus/jev/backend.py.

🤖 Generated with Claude Code

https://claude.ai/code/session_01P4Nm4MVSMmG6JyZi8WumtK

---

Generated by Claude Code