Refactor local model configurations and update tests

- Updated local model configurations to use Nemotron-Mini-4B-Instruct instead of NVIDIA-Nemotron-3-Nano-4B-BF16.
- Adjusted tests to reflect changes in model keys and trust_remote_code settings.
- Removed auto_class attribute from LocalModel as it is no longer necessary.
- Implemented compatibility shims for removed predicates in transformers 5.x to ensure backward compatibility with remote code imports.
- Enhanced test coverage for the new compatibility shims and ensured all tests pass.

docs/adr/0033-local-inproc-transformers-backend.md

@@ -96,8 +96,8 @@ backend stays inactive and the deterministic stub owns the no-config demo path.
   within a session.
 - **Prize-lane impact:** one sponsor family per tier, so a single in-process cast spans
   four tracks at once — **NVIDIA Nemotron** (`tiny`, also the **Tiny Titan** ≤4B lane via
-  Nemotron-3-Nano-4B), **OpenBMB / MiniCPM** (`fast`), **Cohere / Aya** (`balanced`), and
-  **JetBrains / Mellum** (`strong`) — plus the **Community Choice** on-device-inference
+  Nemotron-Mini-4B-Instruct), **OpenBMB / MiniCPM** (`fast`), **Cohere / Aya** (`balanced`),
+  and **JetBrains / Mellum** (`strong`) — plus the **Community Choice** on-device-inference
   story for the HF Space demo.
 
 **Negative / Risks:**
@@ -119,13 +119,15 @@ backend stays inactive and the deterministic stub owns the no-config demo path.
 - `llamacpp_catalogue.py` and `llamacpp_server.py` are deleted; `app.py`'s
   `gpu_selftest` `@spaces.GPU` guard is retained — it detects ZeroGPU availability at
   startup and is unrelated to the inference path.
-- Each tier is tagged with a distinct sponsor model (NVIDIA Nemotron-3-Nano-4B-BF16 ·
+- Each tier is tagged with a distinct sponsor model (NVIDIA Nemotron-Mini-4B-Instruct ·
   OpenBMB MiniCPM4.1-8B · Cohere Aya-Expanse-8B · JetBrains Mellum2-12B-A2.5B-Instruct), so
   a cross-sponsor cast runs on the Space's own GPU. This trades ZeroGPU quota/RAM headroom
   (several multi-GB loads per show) for multi-track coverage; the `tiny` model is listed
-  first so any untagged fallback lands on the cheapest tier. Two deployment notes: Aya is a
-  **gated** repo (needs licence acceptance + `HF_TOKEN`), and Mellum loads via
-  `AutoModelForMultimodalLM` (a per-model `auto_class` on `LocalModel`).
+  first so any untagged fallback lands on the cheapest tier. Notes: Aya is a **gated** repo
+  (needs licence acceptance + `HF_TOKEN`); MiniCPM ships v4-era custom code, so the provider
+  back-fills the `is_torch_fx_available`/`is_torch_sdpa_available` symbols transformers 5.x
+  removed; and the NVIDIA tier uses Nemotron-**Mini** (a plain transformer), not the
+  Nemotron-Nano hybrid, which hard-requires the mamba-ssm kernel that will not build on a Space.
 - Tests live in `tests/test_local_backend.py`. All 676 tests pass; the capability-gate
   logic is fully covered without a GPU or torch import in test processes.
 

docs/architecture/model-routing.md

@@ -111,10 +111,10 @@ a single cast spans four sponsors at once (the multi-track strategy):
 
 | Key | Model | Tier | Notes |
 |---|---|---|---|
-| `local:nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16` | Nemotron Nano 4B | **tiny** | NVIDIA lane; Tiny-Titan ≤4B band; `trust_remote_code`; Mamba-2 hybrid (BF16, not GGUF) |
-| `local:openbmb/MiniCPM4.1-8B` | MiniCPM 4.1 8B | fast | OpenBMB lane; `trust_remote_code` |
+| `local:nvidia/Nemotron-Mini-4B-Instruct` | Nemotron Mini 4B | **tiny** | NVIDIA lane; Tiny-Titan ≤4B band; plain Nemotron-4 transformer (native, no kernels) |
+| `local:openbmb/MiniCPM4.1-8B` | MiniCPM 4.1 8B | fast | OpenBMB lane; `trust_remote_code` (v4-symbol shim applied) |
 | `local:CohereLabs/aya-expanse-8b` | Aya Expanse 8B | balanced | Cohere lane; **gated repo** — needs licence acceptance + `HF_TOKEN` |
-| `local:JetBrains/Mellum2-12B-A2.5B-Instruct` | Mellum 2 (12B MoE, ~2.5B active) | strong | JetBrains lane; loads via `AutoModelForMultimodalLM` |
+| `local:JetBrains/Mellum2-12B-A2.5B-Instruct` | Mellum 2 (12B MoE, ~2.5B active) | strong | JetBrains lane; native `MellumConfig` (Instruct, not Base) |
 
 Each tier is tagged, so a cast's `fast`/`balanced`/`strong` seats route to different sponsor
 models. That cross-sponsor cast loads several multi-GB models per show — heavy on the free
@@ -126,7 +126,7 @@ Bind a tier to a local model with a qualified key:
 
 ```yaml
 profiles:
-  tiny: { endpoint: "local:nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16", temperature: 0.7, max_tokens: 192 }
+  tiny: { endpoint: "local:nvidia/Nemotron-Mini-4B-Instruct", temperature: 0.7, max_tokens: 192 }
 ```
 
 ### Real cost → Governor

docs/blog/03-one-engine-three-costumes.md

@@ -19,7 +19,35 @@ Here are the four.
 3. **Agents** — near-stateless functions that read context and emit a single typed event.
 4. **Projections** — pure functions that fold the event stream into any view you need.
 
-Everything else is configuration. Let's take them one at a time.
+Everything else is configuration. And the shape of how they fit together is the whole
+design — one write side, one scheduler, thin emitters, and many pure reads:
+
+```mermaid
+flowchart LR
+    C["<b>Conductor</b><br/>schedules · meters · drives the loop"]
+    G["<b>Governor</b><br/>calls · tokens · spend"]
+    A["<b>Agents</b><br/>thin · stateless<br/>one typed event each"]
+    L[("<b>Append-only Ledger</b><br/>single source of truth")]
+
+    C -->|"act(projection, recent_events)"| A
+    A -->|"append one Event"| L
+    L -->|"rebuild_stage(events)"| C
+    G -.->|"check() before every act"| C
+
+    subgraph reads["READ SIDE — every view is a pure fold of the log"]
+        direction LR
+        P1["stage view"]
+        P2["each agent's memory"]
+        P3["stats · governor panel"]
+        P4["judge's transcript"]
+        P5["exported JSONL trace"]
+    end
+    L --> P1 & P2 & P3 & P4 & P5
+```
+
+The arrows only ever point one way into the ledger: **agents append, everything else reads.**
+There is no arrow from an agent to another agent. Hold that picture; the rest of this part is
+the four boxes, one at a time.
 
 ---
 
@@ -49,12 +77,66 @@ one log**. Three properties fall out of that, for free:
 - **The system is observable by default.** The ledger *is* the audit trail. What you'd
   normally bolt on as logging is the primary data structure.
 
-An event is a small, strictly-validated Pydantic record — an `id`, a `run_id`, a `turn`, a
-`kind`, an `actor`, and a `payload`, with `extra="forbid"` so a typo'd field is a loud
-error, not a silent one. The `kind` is the interesting part, and it's the subject of
+### The event envelope
+
+An event is a small, strictly-validated Pydantic v2 record with `extra="forbid"`, so a
+typo'd field is a loud error, not a silent one. The whole envelope is flat — no nesting, no
+inheritance:
+
+```mermaid
+classDiagram
+    class Event {
+        +str id  «UUID — idempotency key»
+        +str run_id  «which run»
+        +int turn  «sim-clock tick»
+        +EventKind kind  «regex-validated open string»
+        +str actor  «who emitted it»
+        +dict payload  «shape is per-kind convention»
+        +datetime created_at
+        +int schema_version = 1
+        +str? session_id  «which browser drove the run»
+        +str? model_profile  «route key requested»
+        +str? model_id  «concrete model that ran»
+    }
+```
+
+The `kind` is the interesting part, and it's the subject of
 [Part 5](05-the-ledger-is-the-database.md): it's an *open*, format-validated string, not a
-closed enum. A new scenario mints `clue.found` or `episode.published` without editing a
-single core file. That openness is what lets the engine stay still while the worlds move.
+closed enum. A field validator enforces a lowercase, dot-namespaced shape —
+
+```python
+_KIND_RE = re.compile(r"^[a-z][a-z0-9]*(?:\.[a-z][a-z0-9]*)+$")  # "agent.spoke", "clue.found"
+
+@field_validator("kind")
+@classmethod
+def _validate_kind(cls, value: str) -> str:
+    if not is_valid_kind(value):
+        raise ValueError(f"invalid event kind {value!r}")
+    return value
+```
+
+— but the *set* of kinds is open. A new scenario mints `clue.found` or `episode.published`
+without editing a single core file; the schema validates the *shape* of a kind, while each
+agent's `manifest.may_emit` governs the *authority* to emit one. That split — open shape,
+scoped authority — is what lets the engine stay still while the worlds move.
+
+### One write path, idempotent by id
+
+There is exactly one mutation in the system: `append`. It's a list and a set, and it's
+idempotent against the event's UUID so a retried conductor step can't double-write:
+
+```python
+def append(self, event: Event) -> Event:
+    if event.id in self._seen_ids:   # already have it — no-op
+        return event
+    self._events.append(event)
+    self._seen_ids.add(event.id)
+    return event
+```
+
+The in-memory version above is the offline default; a `SqlAlchemyLedger` implements the
+*same* contract over SQLite or Postgres. How one contract drives two backends, and why
+ordering uses a server-assigned offset rather than the id, is [Part 5](05-the-ledger-is-the-database.md).
 
 ---
 
@@ -73,36 +155,119 @@ It schedules on two tracks, and most scenarios use both:
   regardless of what anyone said. This is how a judge synthesises every few turns, or a
   narrator keeps the world drifting even when the table goes quiet.
 
-Reactive agents drain *before* the tick batch, so an agent that should answer a disturbance
-always speaks before the scheduled rhythm resumes. And both tracks run under the
-**governor** — the runtime safety valve. Many tiny models posting to a shared board is
-exactly the topology that produces a surprise bill, so the governor caps `max_turns`,
-`max_calls_per_turn`, and `max_total_calls` (with optional token and spend ceilings on top).
-When a bound trips it raises a named `BudgetExceeded` that the UI surfaces as a graceful
-end-of-show, not a hung process. The governor gets its own treatment in
-[Part 5](05-the-ledger-is-the-database.md); here it's enough to know the conductor checks it
-before *every* scheduled agent.
+The two tracks run in a fixed order every step. Reactive agents drain *first*, so an agent
+that should answer a disturbance always speaks before the scheduled rhythm resumes:
+
+```mermaid
+flowchart TD
+    S(["step() → _tick(): turn += 1"]) --> Gov["governor.begin_turn(turn)<br/>governor.check(turn)"]
+    Gov --> P1["<b>Track 1 — drain trigger queue (FIFO)</b><br/>agents whose subscribes_to matched<br/>last step's events"]
+    P1 --> P2["<b>Track 2 — run tick agents</b><br/>schedule.tick_every fires this turn"]
+    P2 --> Snap["maybe snapshot every N"]
+    P1 -.->|"each act() appends an Event"| N
+    P2 -.->|"each act() appends an Event"| N["_notify_subscribers(event)<br/>queue matching agents"]
+    N -.->|"feeds the NEXT step's Track 1"| P1
+```
+
+The queueing rule is one method, and it carries the single most important guardrail in the
+whole scheduler — *never queue an agent for its own event*:
+
+```python
+def _notify_subscribers(self, event: Event) -> None:
+    for agent in self.scenario.agents:
+        if event.actor == agent.name:          # never react to yourself
+            continue
+        if event.kind in agent.manifest.subscribes_to:
+            self._trigger_queue.append((agent, event))
+```
+
+Both tracks run under the **governor** — the runtime safety valve. Many tiny models posting
+to a shared board is exactly the topology that produces a surprise bill, so the governor caps
+calls and spend on five axes, checked before *every* scheduled agent:
+
+```python
+@dataclass
+class Governor:
+    max_turns: int = 100              # the show ends after N turns
+    max_calls_per_turn: int = 8       # no single turn fires more than N model calls
+    max_total_calls: int = 500        # whole-run call cap
+    max_total_tokens: int | None = None   # optional token ceiling
+    hourly_budget_usd: float | None = None # optional spend ceiling
+```
+
+When a bound trips it raises a named `BudgetExceeded(reason=...)` that the conductor turns
+into a graceful `run.finished` rather than a hung process. The governor gets its own
+treatment in [Part 5](05-the-ledger-is-the-database.md); here it's enough to see it sits on
+the control path, not beside it — `max_calls_per_turn` is also what makes the subscription
+model safe, because it bounds the fan-out a single cascade can produce within one turn.
 
 > **What broke, and what it taught us.** An early agent that both *subscribed to* and
 > *emitted* `agent.spoke` re-triggered itself on its own event — a one-agent feedback loop
-> that burned the per-turn call cap before the judge ever fired. The fix is one line of
-> principle in the conductor: never queue an agent for its own event. Self-cascade is the
-> first bug a subscription model invites; name it and guard it early.
+> that burned the per-turn call cap before the judge ever fired. The fix is the
+> `event.actor == agent.name` line above: never queue an agent for its own event.
+> Self-cascade is the first bug a subscription model invites; name it and guard it early.
 
 ---
 
 ## 3. Agents: stateless functions that emit one event
 
-An agent is deliberately thin. It owns two things: a **persona string** and **the single
-typed event it emits** this turn. It does not own its prompt layout, its memory, or any
-knowledge of the other agents. It reads a context the engine assembled for it, calls its
-model, and posts one event back to the ledger.
+An agent is deliberately thin. The base interface is a single method — read the context the
+engine assembled, emit one typed event:
+
+```python
+class Agent(ABC):
+    name: str
+
+    @abstractmethod
+    def act(
+        self,
+        run_id: str,
+        turn: int,
+        projection: StageProjection,      # the current stage, folded from the log
+        recent_events: tuple[Event, ...], # the window it's allowed to see
+    ) -> Event:                            # exactly one event back
+        ...
+```
+
+It owns two things: a **persona string** and **the single typed event it emits** this turn.
+It does not own its prompt layout, its memory, or any knowledge of the other agents. The
+concrete `ManifestAgent` is driven entirely by a YAML manifest — persona, what it subscribes
+to, what it may emit, its schedule, and crucially, a *logical model profile* rather than a
+concrete model:
+
+```yaml
+name: clue-gatherer
+role: worker
+persona: >
+  You are a careful Clue Gatherer. Extract exactly one new, concrete clue
+  from the current scene.
+subscribes_to: []
+may_emit: [agent.spoke]
+schedule:
+  tick_every: 1
+model_profile: fast        # tiny ≤4B · fast ≤7B · balanced ≤13B · strong ≤32B
+memory:
+  window: 8
+```
+
+That `model_profile` is the swap point. Because an agent declares only a *profile*, the
+`ModelRouter` can place a different small model behind each one — a ≤4B worker next to a
+stronger judge — without the agent knowing or caring:
+
+```mermaid
+flowchart LR
+    M["AgentManifest<br/>model_profile: fast"] --> R{"ModelRouter<br/>.for_profile('fast')"}
+    R -->|"offline (no key)"| Stub["DeterministicTinyModel<br/>fixed structured output"]
+    R -->|"live"| GW["OpenAI-compatible gateway"]
+    GW --> Cat["concrete ≤32B model<br/>gpt-oss · MiniCPM · Nemotron · gemma"]
+    M -. "model_endpoint: …" .-> Pin["pin one specific catalogue model<br/>(bypasses the tier)"]
+    Pin --> GW
+```
 
-That thinness is what makes the cast swappable. Because an agent declares only a logical
-model *profile* (`tiny`, `fast`, `balanced`, `strong`) rather than a concrete model, the
-router can place a different small model behind each one — a ≤4B worker next to a stronger
-judge — without the agent knowing or caring. How that routing works, and why it's the whole
-prize strategy, is [Part 5](05-the-ledger-is-the-database.md).
+The router is the single place a model is ever named — which is why one cast can legitimately
+run several different sponsor models in the same show, and why offline every profile resolves
+to a deterministic stub so the demo runs with no key. The routing tiers, the decoding configs,
+and why that's the whole prize strategy are [Part 5](05-the-ledger-is-the-database.md).
 
 The "agents never call each other" rule isn't decoration; it's the originality hook. The
 cast of a four-player bluff game are four agents that have *never exchanged a line*. They
@@ -119,12 +284,55 @@ shared memory store.
 > decoupling agents is the goal, but *decoupled is not the same as deaf*. They must still
 > hear each other through the ledger.
 
+### One turn, end to end
+
+The four abstractions only become a *show* when they run in sequence. Here is a single
+acting agent, from the conductor's `check()` to the rendered diff — the loop that repeats
+until the governor calls time:
+
+```mermaid
+sequenceDiagram
+    participant C as Conductor
+    participant G as Governor
+    participant A as Agent
+    participant CB as ContextBuilder
+    participant R as ModelRouter
+    participant L as Ledger
+    participant O as Observer
+    C->>G: check(turn)  «trip BudgetExceeded if over»
+    C->>A: act(projection, recent_events)
+    A->>CB: build(persona, projection, memory, role)
+    CB-->>A: layered prompt string
+    A->>R: for_profile(model_profile)
+    R-->>A: small model → one typed Event
+    A-->>C: Event  «kind must be in may_emit»
+    C->>G: record_call(tokens, cost)
+    C->>L: append(event)  «idempotent on id»
+    C->>O: consume(event) → ViewDiff
+    Note over C,L: _notify_subscribers queues agents for the NEXT step
+```
+
+Cognition (the agent + router) and bookkeeping (governor + ledger) and presentation (the
+observer) are three separate concerns strung on one append. None of them know about the
+others; they only know the event.
+
 ---
 
 ## 4. Projections: every view is a pure fold
 
-A projection is a pure function from the event list to some view. The stage projection folds
-`world.observed` into a `current_scene` and `agent.spoke` into the running list of notes.
+A projection is a pure function from the event list to some view. The whole stage is one
+small reducer — fold each event into a mutable snapshot:
+
+```python
+def rebuild_stage(events: tuple[Event, ...], run_id: str | None = None) -> StageProjection:
+    projection = StageProjection()
+    if run_id is not None:
+        events = tuple(e for e in events if e.run_id == run_id)
+    for event in events:
+        projection.apply(event)     # world.observed → current_scene; agent.spoke → notes; …
+    return projection
+```
+
 The stats panel folds calls and tokens. Each agent's memory is a filtered fold over the
 events it's allowed to see. The Fishbowl's scrub-anywhere replay is the same fold over a
 *prefix* of the log — `rebuild_stage(events[:k])` — which is why scrubbing back through a
@@ -147,19 +355,69 @@ flowchart LR
 ![The Fishbowl Show rendering Thousand Token Wood: MindCards around a scene, narrator feed, and meters — all derived from the event log.](images/show-thousand-token-wood.png)
 *The Show is just one read side: the stage, the cards, the feed, and the meters are all pure projections of the same append-only log.*
 
+### The observer: a camera crew, never an actor
+
 The **observer** is the cleanest expression of the rule. It consumes events read-only and
-computes a `ViewDiff` — the delta to render — and it *never appends*. Rendering is a camera
-crew, not an actor. The world runs identically whether or not anyone is watching, you can
-attach several observers to one ledger at once (a stage view and a feed and a split table),
-and post-hoc analysis is just another observer fed a saved log. Cognition and presentation
-never touch.
+computes a `ViewDiff` — the delta to render — and it *never appends*:
+
+```python
+def consume(self, event: Event) -> ViewDiff:
+    prev_scene = self._view.current_scene
+    prev_notes = list(self._view.agent_notes)
+    self._view.apply(event)               # advance the read-side snapshot
+    diff = ViewDiff(
+        scene_changed=self._view.current_scene != prev_scene,
+        new_agent_notes=[n for n in self._view.agent_notes if n not in prev_notes],
+        # … new_judge_notes, new_user_artifacts
+    )
+    if diff.has_changes:
+        for cb in self._callbacks:        # push to UI / SSE / WebSocket
+            cb(diff)
+    return diff
+```
+
+```mermaid
+flowchart LR
+    Conductor --> Agents
+    Agents -->|append| L[("Ledger")]
+    L -->|read only| Obs["Observer.consume(event)"]
+    Obs --> Diff["ViewDiff — scene_changed,<br/>new notes, new artifacts"]
+    Diff --> Out1["Gradio stage"]
+    Diff --> Out2["cognition graph"]
+    Diff --> Out3["plain chat log"]
+```
+
+Rendering is a camera crew, not an actor. The world runs identically whether or not anyone
+is watching, you can attach several observers to one ledger at once (a stage view and a feed
+and a split table), and post-hoc analysis is just another observer fed a saved log. Cognition
+and presentation never touch.
 
 ---
 
 ## Two scenarios, zero engine edits
 
 The proof that the abstraction holds is that wildly different *cognitive shapes* need no
-engine changes — only config.
+engine changes — only config. Two scenarios, two YAML files, opposite scheduling topologies
+on the *same* conductor:
+
+```mermaid
+flowchart TB
+    subgraph TTW["thousand-token-wood.yaml — divergent"]
+        direction LR
+        sk["seedkeeper"] -.-> b1[("ledger")]
+        pa["pocket-actor"] -.-> b1
+        ec["echo"] -.-> b1
+        cr["critic"] -.-> b1
+        b1 -.-> sk & pa & ec & cr
+    end
+    subgraph MR["mystery-roots.yaml — convergent"]
+        direction LR
+        cg["clue-gatherer"] --> hf["hypothesis-former"]
+        hf --> da["devil's-advocate"]
+        da --> mj["mystery-judge"]
+        mj -->|narrows| cg
+    end
+```
 
 **Thousand Token Wood** is divergent. The scene gets stranger turn by turn; a seedkeeper
 narrates, a pocket actor wants impossible things, an echo transforms visitor disturbances, a
@@ -168,11 +426,25 @@ winner — the ledger *is* the story.
 
 **Mystery Roots** is convergent. A mystery is stated, a clue-gatherer extracts evidence, a
 hypothesis-former proposes, a devil's advocate attacks, and a judge rules. Scheduling is a
-tight multi-phase cycle that narrows toward an answer.
+tight multi-phase cycle that narrows toward an answer. The difference between the two lives
+entirely in their config — cast list, schedule, and a `competition` block:
+
+```yaml
+# mystery-roots.yaml            # twenty-sprouts.yaml
+cast:                           cast:
+  - clue-gatherer                 - sprout-guesser
+  - hypothesis-former             - secret-keeper
+  - devils-advocate               - sprout-judge
+  - mystery-judge               competition:
+competition:                      kind: versus
+  kind: judged                    teams:
+                                    guesser: [sprout-guesser]
+                                    keeper: [secret-keeper]
+```
 
 Same conductor. Same ledger. Same governor. Same context builder. Same memory. **Different
 cast, different schedule, different cognitive shape** — and the difference is entirely in
-two YAML files. The engine is plumbing; the scenario is data.
+those YAML files. The engine is plumbing; the scenario is data.
 
 This isn't an aspiration we're trusting ourselves to honour. `tests/test_modularity.py`
 builds every scenario config and asserts the invariants hold, so the *first* time someone
@@ -187,9 +459,13 @@ scenarios standing on one engine.
 |---|---|---|
 | UI | Gradio (custom-themed Fishbowl) | Hackathon-required; the theater is built on the ledger's read surface, so it's swappable |
 | Event schema | Pydantic v2, `extra="forbid"` | Strict validation; a stray field is a loud error |
-| Event `kind` | Open, format-validated string | A scenario mints new kinds with zero engine edits (ADR-0009) |
+| Event `kind` | Open, regex-validated string | A scenario mints new kinds with zero engine edits (ADR-0009) |
+| Authority to emit | Per-agent `manifest.may_emit` | Open *shape*, scoped *authority* — shape and permission are decoupled |
+| Scheduling | Two-track: subscriptions + ticks | Reaction *and* heartbeat; reactive drains before the tick batch |
+| Safety | `Governor`, checked before every act | Many tiny models on a shared board is a surprise-bill topology; cap it on five axes |
 | Models | Small models (≤32B) behind a profile router | One cast can run several sponsor models at once — see Part 5 |
 | Memory | Ledger view, no separate store | Consistency, crash recovery, and testability for free — see Part 4 |
+| Rendering | Read-only `Observer` → `ViewDiff` | Cognition and presentation never touch; N observers per ledger |
 | Orchestration | In-process, synchronous conductor | Right size for a live demo; durable execution is available when a run needs it |
 
 ---
@@ -197,9 +473,10 @@ scenarios standing on one engine.
 ## The throughline
 
 Four abstractions. A log you only append to, a manager who schedules and meters, thin agents
-that emit one event each, and pure folds that turn the log into every view. Stack them and
-you get a system that is reproducible, recoverable, testable, and — the part that matters for
-a hackathon — *extensible by writing YAML instead of Python*.
+that emit one event each, and pure folds that turn the log into every view. The arrows only
+point one way — agents append, everything else reads — and that single constraint is what
+buys a system that is reproducible, recoverable, testable, and, the part that matters for a
+hackathon, *extensible by writing YAML instead of Python*.
 
 The next two parts go deeper into the two abstractions that do the most quiet work. Part 4
 opens the agent's-eye view: how the context builder and the three-layer memory decide what a

src/models/local_catalogue.py

@@ -65,10 +65,7 @@ class LocalModel:
     ``transformers``). ``profile`` is the tier this model is the default casting for, or
     None for an alternate the cast can still pin explicitly. ``source`` is a friendly
     family/org label for the picker. ``trust_remote_code`` is forwarded to
-    ``from_pretrained`` for repos that ship custom modelling code (e.g. MiniCPM, Nemotron).
-    ``auto_class`` is the ``transformers`` auto-class the provider loads the repo with —
-    ``AutoModelForCausalLM`` for an ordinary LM, overridden where a model card calls for a
-    different one (e.g. JetBrains Mellum loads with ``AutoModelForMultimodalLM``).
+    ``from_pretrained`` for repos that ship custom modelling code (e.g. MiniCPM).
     """
 
     repo_id: str
@@ -76,7 +73,6 @@ class LocalModel:
     params_b: float | None = None
     source: str = "Hugging Face"
     trust_remote_code: bool = False
-    auto_class: str = "AutoModelForCausalLM"
 
     @property
     def key(self) -> str:
@@ -103,15 +99,14 @@ class LocalModel:
 
 LOCAL_MODELS: tuple[LocalModel, ...] = (
     # Tiny tier (≤4B, Tiny-Titan band) — the cast-wide fallback default. NVIDIA Nemotron
-    # Nano is a Mamba-2/Transformer hybrid; load the BF16 (safetensors) sibling, not the
-    # GGUF, since the in-process path runs transformers. Ships custom modelling code, so
-    # trust_remote_code is required.
+    # Mini 4B is a plain Nemotron-4 transformer (native in transformers, no custom code and
+    # no Mamba kernels), so it loads in-process cleanly — unlike the Nemotron-Nano hybrid,
+    # which hard-requires the mamba-ssm CUDA kernel that will not build on a Space.
     LocalModel(
-        repo_id="nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16",
+        repo_id="nvidia/Nemotron-Mini-4B-Instruct",
         profile="tiny",
         params_b=4.0,
         source="NVIDIA Nemotron",
-        trust_remote_code=True,
     ),
     # Fast tier — OpenBMB MiniCPM 4.1 8B. Ships custom modelling code (trust_remote_code).
     LocalModel(
@@ -131,14 +126,14 @@ LOCAL_MODELS: tuple[LocalModel, ...] = (
         source="Cohere Labs Aya",
     ),
     # Strong tier — JetBrains Mellum 2 (12B MoE, ~2.5B active). The Instruct variant (a
-    # post-trained assistant with a chat template), not the Base completion model. Its card
-    # loads it with AutoModelForMultimodalLM, so we pin that auto-class.
+    # post-trained assistant with a chat template), not the Base completion model. MellumConfig
+    # is native in transformers, so it loads with the default AutoModelForCausalLM (the card's
+    # AutoModelForMultimodalLM is wrong for this arch) and needs no custom code.
     LocalModel(
         repo_id="JetBrains/Mellum2-12B-A2.5B-Instruct",
         profile="strong",
         params_b=12.0,
         source="JetBrains Mellum",
-        auto_class="AutoModelForMultimodalLM",
     ),
 )
 

src/models/local_provider.py

@@ -50,7 +50,35 @@ from src.models.provider import ModelProvider, estimate_tokens, model_error
 _LOADED: dict[str, tuple] = {}
 
 
-def _ensure_loaded(repo_id: str, trust_remote_code: bool, auto_class: str = "AutoModelForCausalLM") -> tuple:
+def _always_true(*_args, **_kwargs) -> bool:
+    return True
+
+
+# v4-era capability predicates that transformers 5.x removed but Hub ``trust_remote_code``
+# modelling files still import (e.g. MiniCPM's modeling_minicpm.py does
+# ``from transformers.utils.import_utils import is_torch_fx_available``). All of these are
+# unconditionally True at this project's torch>=2.8 floor — exactly the value the
+# transformers maintainers say is now correct (transformers#44561) — so back-filling them
+# lets such remote code import instead of crashing with ``cannot import name '…'``.
+_REMOVED_TORCH_PREDICATES = ("is_torch_fx_available", "is_torch_sdpa_available")
+
+
+def _ensure_transformers_v4_symbols() -> None:
+    """Restore removed v4-era predicates onto ``transformers.utils`` so older Hub remote
+    code (loaded via ``trust_remote_code``) imports cleanly. Idempotent — only fills a name
+    that is genuinely absent, so it never shadows a function transformers still ships."""
+    try:
+        import transformers.utils as tu
+        from transformers.utils import import_utils
+    except Exception:  # pragma: no cover - transformers absent → offline path, nothing to do
+        return
+    for mod in (import_utils, tu):
+        for name in _REMOVED_TORCH_PREDICATES:
+            if not hasattr(mod, name):
+                setattr(mod, name, _always_true)
+
+
+def _ensure_loaded(repo_id: str, trust_remote_code: bool) -> tuple:
     """Load (once, cached) the tokenizer + model for *repo_id* **on CPU**.
 
     Called from :meth:`LocalTransformersProvider.complete` in the parent process to warm
@@ -75,19 +103,18 @@ def _ensure_loaded(repo_id: str, trust_remote_code: bool, auto_class: str = "Aut
     """
     if repo_id in _LOADED:
         return _LOADED[repo_id]
-    import transformers
-    from transformers import AutoTokenizer
+    from transformers import AutoModelForCausalLM, AutoTokenizer
 
-    # The auto-class is per-model (most are AutoModelForCausalLM; some cards call for another,
-    # e.g. Mellum's AutoModelForMultimodalLM) — resolve it by name off the transformers module.
-    model_cls = getattr(transformers, auto_class)
+    # Back-fill v4-era symbols removed in transformers 5.x before any trust_remote_code
+    # modelling file is imported (tokenizer or model), or it crashes at import time.
+    _ensure_transformers_v4_symbols()
     tokenizer = AutoTokenizer.from_pretrained(repo_id, trust_remote_code=trust_remote_code)
     try:
-        model = model_cls.from_pretrained(
+        model = AutoModelForCausalLM.from_pretrained(
             repo_id, dtype="auto", low_cpu_mem_usage=False, trust_remote_code=trust_remote_code
         )
     except TypeError:  # pragma: no cover - older transformers use the torch_dtype kwarg name
-        model = model_cls.from_pretrained(
+        model = AutoModelForCausalLM.from_pretrained(
             repo_id, torch_dtype="auto", low_cpu_mem_usage=False, trust_remote_code=trust_remote_code
         )
     # Re-tie the output head to the (materialized) input embeddings so no parameter is left
@@ -98,7 +125,7 @@ def _ensure_loaded(repo_id: str, trust_remote_code: bool, auto_class: str = "Aut
     return _LOADED[repo_id]
 
 
-def _gpu_duration(repo_id, trust_remote_code, auto_class, system, prompt, max_new_tokens, temperature, top_p) -> int:
+def _gpu_duration(repo_id, trust_remote_code, system, prompt, max_new_tokens, temperature, top_p) -> int:
     """Dynamic ``@spaces.GPU`` duration (seconds) for one generation.
 
     Scales with the token budget and stays short so the Space keeps high queue priority on
@@ -109,7 +136,7 @@ def _gpu_duration(repo_id, trust_remote_code, auto_class, system, prompt, max_ne
 
 
 @spaces.GPU(duration=_gpu_duration)
-def _generate(repo_id, trust_remote_code, auto_class, system, prompt, max_new_tokens, temperature, top_p):
+def _generate(repo_id, trust_remote_code, system, prompt, max_new_tokens, temperature, top_p):
     """Run one chat completion on the GPU; return ``(text, prompt_tokens, completion_tokens)``.
 
     Module-level and decorated so ZeroGPU registers it and grants a GPU for the call. The
@@ -122,7 +149,7 @@ def _generate(repo_id, trust_remote_code, auto_class, system, prompt, max_new_to
     """
     import torch
 
-    tokenizer, model = _ensure_loaded(repo_id, trust_remote_code, auto_class)
+    tokenizer, model = _ensure_loaded(repo_id, trust_remote_code)
     if torch.cuda.is_available():
         model = model.to("cuda")
     device = next(model.parameters()).device
@@ -181,12 +208,11 @@ class LocalTransformersProvider(ModelProvider):
                 # Warm the weights in the PARENT first so the forked @spaces.GPU call
                 # inherits them (see module docstring); this is a cache hit after the
                 # first use of this model in the process.
-                _ensure_loaded(self.model, self._trust_remote_code(), self._auto_class())
+                _ensure_loaded(self.model, self._trust_remote_code())
                 system = OpenAICompatProvider._system_for_role(role)
                 text, prompt_tokens, completion_tokens = _generate(
                     self.model,
                     self._trust_remote_code(),
-                    self._auto_class(),
                     system,
                     prompt,
                     self.max_tokens,
@@ -214,18 +240,6 @@ class LocalTransformersProvider(ModelProvider):
         entry = local_catalogue.model_by_key(self.model)
         return bool(entry.trust_remote_code) if entry is not None else False
 
-    def _auto_class(self) -> str:
-        """The ``transformers`` auto-class to load this repo with (from the catalogue).
-
-        Most models load with ``AutoModelForCausalLM``; a few cards call for another (e.g.
-        JetBrains Mellum → ``AutoModelForMultimodalLM``). An off-catalogue id defaults to
-        ``AutoModelForCausalLM`` — the ordinary case for a hand-pinned chat model.
-        """
-        from src.models import local_catalogue
-
-        entry = local_catalogue.model_by_key(self.model)
-        return entry.auto_class if entry is not None else "AutoModelForCausalLM"
-
     def _record_usage(self, prompt_tokens: int, completion_tokens: int, prompt: str, text: str) -> None:
         # Generation returns exact token counts; fall back to an estimate only if a count
         # came back as zero (e.g. an empty decode), so the Governor always sees a budget hit.

tests/test_local_backend.py

@@ -36,7 +36,7 @@ def test_one_sponsor_model_per_tier_and_sizes_stay_small():
 
 
 def test_every_tier_resolves_to_its_sponsor_model():
-    assert local_catalogue.default_key_for_profile("tiny") == "nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16"
+    assert local_catalogue.default_key_for_profile("tiny") == "nvidia/Nemotron-Mini-4B-Instruct"
     assert local_catalogue.default_key_for_profile("fast") == "openbmb/MiniCPM4.1-8B"
     assert local_catalogue.default_key_for_profile("balanced") == "CohereLabs/aya-expanse-8b"
     assert local_catalogue.default_key_for_profile("strong") == "JetBrains/Mellum2-12B-A2.5B-Instruct"
@@ -45,25 +45,19 @@ def test_every_tier_resolves_to_its_sponsor_model():
 
 
 def test_model_by_key_carries_trust_remote_code():
-    # Nemotron + MiniCPM ship custom modelling code; Aya (native Command arch) does not; an
-    # off-catalogue id is unknown.
-    assert local_catalogue.model_by_key("nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16").trust_remote_code is True
+    # MiniCPM ships custom modelling code; the native-arch models (Nemotron-Mini, Aya) do
+    # not; an off-catalogue id is unknown.
     assert local_catalogue.model_by_key("openbmb/MiniCPM4.1-8B").trust_remote_code is True
+    assert local_catalogue.model_by_key("nvidia/Nemotron-Mini-4B-Instruct").trust_remote_code is False
     assert local_catalogue.model_by_key("CohereLabs/aya-expanse-8b").trust_remote_code is False
     assert local_catalogue.model_by_key("does/not-exist") is None
 
 
-def test_model_by_key_carries_auto_class():
-    # Mellum's card loads it with AutoModelForMultimodalLM; the rest use the default class.
-    assert local_catalogue.model_by_key("JetBrains/Mellum2-12B-A2.5B-Instruct").auto_class == "AutoModelForMultimodalLM"
-    assert local_catalogue.model_by_key("openbmb/MiniCPM4.1-8B").auto_class == "AutoModelForCausalLM"
-
-
 def test_binding_is_a_bare_repo_id_with_no_endpoint():
     # In-process: the binding carries the raw transformers repo id (no openai/ prefix) and
     # neither a base_url nor an api_key — the router builds the in-process provider from it.
-    binding = local_catalogue.binding_for("nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16")
-    assert binding["model"] == "nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16"
+    binding = local_catalogue.binding_for("nvidia/Nemotron-Mini-4B-Instruct")
+    assert binding["model"] == "nvidia/Nemotron-Mini-4B-Instruct"
     assert binding["base_url"] == ""
     assert binding["api_key"] == ""
 
@@ -115,9 +109,9 @@ def test_local_backend_is_registered_and_qualified():
 
 def test_registry_default_and_binding_round_trip():
     key = inference.default_key_for_profile("tiny", "local")
-    assert key == "local:nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16"
+    assert key == "local:nvidia/Nemotron-Mini-4B-Instruct"
     binding = inference.binding_for(key)
-    assert binding["model"] == "nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16"
+    assert binding["model"] == "nvidia/Nemotron-Mini-4B-Instruct"
     assert binding["base_url"] == ""
 
 
@@ -136,15 +130,15 @@ def test_router_dispatches_local_key_to_in_process_provider():
     # A live router resolving a local: key must build the in-process provider (not LiteLLM),
     # bound to the bare repo id. Construction only — no GPU is touched.
     router = ModelRouter(offline=False)
-    provider = router.for_profile("local:nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16")
+    provider = router.for_profile("local:nvidia/Nemotron-Mini-4B-Instruct")
     assert isinstance(provider, LocalTransformersProvider)
-    assert provider.model == "nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16"
-    assert provider.model_id == "nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16"
+    assert provider.model == "nvidia/Nemotron-Mini-4B-Instruct"
+    assert provider.model_id == "nvidia/Nemotron-Mini-4B-Instruct"
 
 
 def test_catalogue_spec_tags_local_kind_and_others_litellm():
     router = ModelRouter(offline=False)
-    local_spec = router._catalogue_spec("local:nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16")
+    local_spec = router._catalogue_spec("local:nvidia/Nemotron-Mini-4B-Instruct")
     assert local_spec is not None and local_spec.kind == "local"
     # An HF key resolves through the same path but stays on the HTTP transport.
     hf_spec = router._catalogue_spec("hf:katanemo/Arch-Router-1.5B")
@@ -155,8 +149,8 @@ def test_catalogue_spec_tags_local_kind_and_others_litellm():
 
 
 def test_provider_reports_model_id_and_zeroed_usage_before_any_call():
-    provider = LocalTransformersProvider(model="nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16")
-    assert provider.model_id == "nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16"
+    provider = LocalTransformersProvider(model="nvidia/Nemotron-Mini-4B-Instruct")
+    assert provider.model_id == "nvidia/Nemotron-Mini-4B-Instruct"
     assert provider.last_usage == {}  # no call yet — matches the sibling providers
     provider._zero_usage()
     assert provider.last_usage == {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0}
@@ -169,16 +163,6 @@ def test_provider_resolves_trust_remote_code_from_catalogue():
     assert LocalTransformersProvider(model="some/random-repo")._trust_remote_code() is False
 
 
-def test_provider_resolves_auto_class_from_catalogue():
-    # Mellum loads with a non-default auto-class; ordinary and off-catalogue repos use CausalLM.
-    assert (
-        LocalTransformersProvider(model="JetBrains/Mellum2-12B-A2.5B-Instruct")._auto_class()
-        == "AutoModelForMultimodalLM"
-    )
-    assert LocalTransformersProvider(model="openbmb/MiniCPM4.1-8B")._auto_class() == "AutoModelForCausalLM"
-    assert LocalTransformersProvider(model="some/random-repo")._auto_class() == "AutoModelForCausalLM"
-
-
 # ── ZeroGPU contract: CUDA only inside @spaces.GPU, never in the parent ───────────────
 # Regression guard for the production crash "Low-level CUDA init (torch._C._cuda_init)
 # reached … ZeroGPU's emulation did not intercept": the parent process gets no GPU, so any
@@ -231,6 +215,26 @@ def test_parent_loader_fully_materialises_weights_no_meta_tensors():
     assert "tie_weights()" in code
 
 
+def test_v4_compat_shim_backfills_removed_remote_code_predicates():
+    # Regression guard for the ZeroGPU error "cannot import name 'is_torch_fx_available'
+    # from transformers.utils.import_utils": transformers 5.x removed these predicates, but
+    # MiniCPM's (and other) trust_remote_code modelling files still import them. The provider
+    # back-fills them (all True at our torch floor) so the remote import succeeds.
+    from src.models import local_provider
+
+    local_provider._ensure_transformers_v4_symbols()
+    from transformers.utils import import_utils
+
+    # Every name the shim covers is importable from transformers.utils.import_utils and True.
+    for name in local_provider._REMOVED_TORCH_PREDICATES:
+        fn = getattr(import_utils, name)
+        assert fn() is True
+    # And _ensure_loaded runs the shim before touching any remote code.
+    import inspect
+
+    assert "_ensure_transformers_v4_symbols()" in inspect.getsource(local_provider._ensure_loaded)
+
+
 def test_gpu_transfer_lives_inside_the_spaces_gpu_function():
     from pathlib import Path