docs/adr/0022-per-agent-explicit-model-binding.md

# ADR-0022: Per-Agent Explicit Model Binding (`model_endpoint`)

## Status

Accepted

## Context

ADR-0010 gave per-agent model selection through four **logical tiers**
(`tiny`/`fast`/`balanced`/`strong`), and `config/models.yaml` binds each tier to one
concrete catalogue model. That is the right default, but it has two limits:

1. **A cast can express at most four distinct models** — one per tier. Two agents on
   the same tier always share a model.
2. **The unbound specialist models are unreachable.** Several catalogue entries have
   `profile=None` (Nemotron Cascade 14B, Nemotron 30B, MiniCPM-o) precisely so they do
   *not* displace a tier default — but then no manifest could ever cast them.

Both bite the hackathon strategy directly: the unfair advantage is running *different
sponsor models in one cast* (Judge → Nemotron, a worker → MiniCPM) to qualify for
multiple tracks from a single submission. And the Fishbowl Lab needed to let a user pick
concrete Modal-hosted models per cast member — with the pick actually driving the run
(the Lab's model controls were previously cosmetic: `on_summon` ignored
`collect_world_config` and always built the scenario's default cast).

## Decision

Add an optional, additive per-agent override that names a **specific catalogue model**,
leaving the tier system as the default and fallback.

- **Manifest.** `AgentManifest` gains `model_endpoint: str | None = None` — a
  `modal/catalogue.py` endpoint slug. `None` → route by `model_profile` (unchanged).
- **Routing.** `ManifestAgent` routes by a **route key** —
  `self._route_key = model_endpoint or model_profile` — and calls
  `router.for_profile(self._route_key)`. The `ModelRouter` already accepts any key;
  `_spec_for` now resolves a non-tier key against the catalogue (`_catalogue_spec`:
  `modal_catalogue.binding_for(key)` for the live model string / endpoint URL / api key,
  with decoding inherited from the model's tier — an unbound specialist → `balanced`).
  An unknown non-tier key degrades to the `fast` tier rather than crashing. Offline this
  path is never reached: `_build` serves the deterministic stub for any key, with the key
  folded into the stub's `variant` so a different pick still varies (reproducible) output.
- **Composed runs.** `Registry.from_world(world)` builds an in-memory registry from a
  validated `WorldConfig`, so a UI- (or LLM-) composed run flows through the same
  `build_scenario` / `build_router` / `governor_for` path as a config-file run.
- **Fishbowl Lab.** The cast section is a `@gr.render` over the scenario: one model
  `gr.Dropdown` per non-judge player (the Judge picks in §04), its choices sourced *only*
  from `modal_catalogue.entries()`. Picks accumulate in a `cast_models` state;
  `collect_world_config` maps each onto the agent's `model_endpoint` (re-checking the key
  against the catalogue), and `Summon` runs the composed world. Only catalogue-hosted
  models are offerable, and the selection is load-bearing.

## Consequences

- A cast can pin **any** catalogue model per agent, including the unbound specialists —
  enabling genuine multi-sponsor-model casts from one engine, one submission.
- The tier abstraction (ADR-0010) is untouched: it remains the default, the decoding
  source, the offline-variant tag, and the fallback. `model_endpoint` is purely additive,
  so every existing manifest, scenario, and test is byte-identical (defaults to `None`).
- The Lab's model picker is now functional, not cosmetic: the model you choose is the
  model that speaks (offline → the deterministic stub, demo still reproducible). A bad
  compose degrades to the scenario's default cast, so Summon never breaks the demo.
- A run cannot point at an undeployed model: the UI offers only catalogue entries, and
  `collect_world_config` re-validates the key, dropping anything out-of-band or stale.
- Offline determinism is preserved end-to-end (the route key, not just the tier, seeds
  the stub).

## Alternatives considered

- **Per-tier rebinding** (let the run choose which catalogue model backs each of the four
  tiers): zero engine change, but still capped at four distinct models and still cannot
  reach the unbound specialists. Rejected as too weak for the multi-sponsor goal.
- **Widening `ModelProfile` to an arbitrary `str`**: would dissolve the tier contract that
  drives decoding defaults, the `MODEL_<TIER>` env overrides, and the offline variant.
  Rejected in favour of a separate, additive field that keeps both concepts crisp.

## Code

- `src/core/manifest.py` — `AgentManifest.model_endpoint`
- `src/agents/base.py` — `ManifestAgent._route_key`
- `src/models/router.py` — `ModelRouter._spec_for` / `_catalogue_spec`
- `src/core/registry.py` — `Registry.from_world`
- `src/ui/fishbowl/lab.py` — `model_choices`, `_cast_defaults`, `_judge_manifest`, the
  cast `gr.render`, `collect_world_config`
- `src/ui/fishbowl/app.py` — `_compose_session`, the `Summon` wiring

See also: ADR-0010 (logical-profile routing), ADR-0011 (declarative validatable config),
ADR-0015 (LiteLLM gateway to Modal models), ADR-0019 (single model catalogue), ADR-0021
(Fishbowl Gradio presenter).