fix: harden OpenBMB backend runtime

app.py

@@ -8,10 +8,12 @@ from puppet_theater import (
     DEFAULT_OPENBMB_MODEL_ID,
     TheaterSession,
     create_show_from_premise,
+    get_backend_status,
     request_finale,
     run_one_beat,
     summon_actor,
     throw_prop,
+    warm_up_openbmb,
 )
 
 
@@ -29,9 +31,16 @@ EMPTY_STAGE = """
 EMPTY_TRANSCRIPT = "No show yet. The transcript will appear here."
 EMPTY_DIRECTOR_LOG = "No director notes yet."
 EMPTY_TRACE = "No trace events yet."
-EMPTY_BACKEND = "Active backend: deterministic\nFallback: deterministic safety path enabled"
+EMPTY_BACKEND = (
+    "Active backend: deterministic\n"
+    "OpenBMB model id: openbmb/MiniCPM5-1B\n"
+    "Model status: unloaded\n"
+    "Fallback: deterministic safety path enabled"
+)
 BACKEND_CHOICES = ["deterministic", "openbmb"]
 OPENBMB_MODEL_ID = os.getenv("OPENBMB_MODEL_ID", DEFAULT_OPENBMB_MODEL_ID)
+DEFAULT_MAX_NEW_TOKENS = 80
+DEFAULT_TEMPERATURE = 0.8
 PLAYBACK_DELAY_SECONDS = 0.75
 PROP_EMOJI = {
     "rubber duck": "🐤",
@@ -920,24 +929,63 @@ def normalize_backend_name(backend_name: str | None) -> str:
     return backend_name if backend_name in BACKEND_CHOICES else "deterministic"
 
 
-def apply_backend_selection(session: TheaterSession | None, backend_name: str | None) -> TheaterSession | None:
+def normalize_max_new_tokens(max_new_tokens: int | float | None) -> int:
+    if max_new_tokens is None:
+        return DEFAULT_MAX_NEW_TOKENS
+    return max(16, min(160, int(max_new_tokens)))
+
+
+def normalize_temperature(temperature: int | float | None) -> float:
+    if temperature is None:
+        return DEFAULT_TEMPERATURE
+    return max(0.0, min(1.5, float(temperature)))
+
+
+def apply_backend_selection(
+    session: TheaterSession | None,
+    backend_name: str | None,
+    max_new_tokens: int | float | None = None,
+    temperature: int | float | None = None,
+) -> TheaterSession | None:
     if session is None:
         return None
     session.backend_name = normalize_backend_name(backend_name)
     session.backend_model_id = OPENBMB_MODEL_ID if session.backend_name == "openbmb" else None
+    session.backend_max_new_tokens = normalize_max_new_tokens(max_new_tokens)
+    session.backend_temperature = normalize_temperature(temperature)
     return session
 
 
-def render_backend_settings(session: TheaterSession | None, backend_name: str | None = None) -> str:
+def render_backend_settings(
+    session: TheaterSession | None,
+    backend_name: str | None = None,
+    max_new_tokens: int | float | None = None,
+    temperature: int | float | None = None,
+) -> str:
     selected_backend = normalize_backend_name(backend_name)
     active_backend = session.backend_name if session is not None else selected_backend
     model_id = session.backend_model_id if session is not None else None
     if active_backend == "openbmb":
         model_id = model_id or OPENBMB_MODEL_ID
+    status = get_backend_status(active_backend)
+    openbmb_status = get_backend_status("openbmb")
+    configured_max_new_tokens = (
+        session.backend_max_new_tokens if session is not None else normalize_max_new_tokens(max_new_tokens)
+    )
+    configured_temperature = (
+        session.backend_temperature if session is not None else normalize_temperature(temperature)
+    )
+    latency = f"{status.latest_latency_ms}ms" if status.latest_latency_ms is not None else "none yet"
+    fallback_reason = status.latest_fallback_reason or "none"
     return (
         f"Active backend: {active_backend}\n"
         "Available backends: deterministic, openbmb\n"
         f"OpenBMB model id: {model_id or 'not selected'}\n"
+        f"Model status: {status.load_status}\n"
+        f"OpenBMB status: {openbmb_status.load_status}\n"
+        f"Latest latency: {latency}\n"
+        f"Latest fallback reason: {fallback_reason}\n"
+        f"Generation: max_new_tokens={configured_max_new_tokens}, temperature={configured_temperature:.2f}\n"
         "Fallback behavior: invalid model output falls back to deterministic actor lines"
     )
 
@@ -952,9 +1000,17 @@ def render_outputs(session: TheaterSession | None):
     )
 
 
-def create_show(premise: str, session: TheaterSession | None, backend_name: str):
+def create_show(
+    premise: str,
+    session: TheaterSession | None,
+    backend_name: str,
+    max_new_tokens: int | float,
+    temperature: int | float,
+):
     premise = premise.strip()
     selected_backend = normalize_backend_name(backend_name)
+    selected_max_new_tokens = normalize_max_new_tokens(max_new_tokens)
+    selected_temperature = normalize_temperature(temperature)
     if not premise:
         return (
             None,
@@ -962,13 +1018,15 @@ def create_show(premise: str, session: TheaterSession | None, backend_name: str)
             "No premise yet. Add a premise to raise the curtain.",
             EMPTY_DIRECTOR_LOG,
             EMPTY_TRACE,
-            render_backend_settings(None, selected_backend),
+            render_backend_settings(None, selected_backend, selected_max_new_tokens, selected_temperature),
         )
 
     session = create_show_from_premise(
         premise,
         backend_name=selected_backend,
         backend_model_id=OPENBMB_MODEL_ID if selected_backend == "openbmb" else None,
+        backend_max_new_tokens=selected_max_new_tokens,
+        backend_temperature=selected_temperature,
     )
     return session, *render_outputs(session)
 
@@ -984,11 +1042,19 @@ def reset_show():
         EMPTY_DIRECTOR_LOG,
         EMPTY_TRACE,
         "deterministic",
+        DEFAULT_MAX_NEW_TOKENS,
+        DEFAULT_TEMPERATURE,
+        True,
         EMPTY_BACKEND,
     )
 
 
-def advance_one_beat(session: TheaterSession | None, backend_name: str):
+def advance_one_beat(
+    session: TheaterSession | None,
+    backend_name: str,
+    max_new_tokens: int | float,
+    temperature: int | float,
+):
     if session is None:
         return (
             None,
@@ -996,15 +1062,21 @@ def advance_one_beat(session: TheaterSession | None, backend_name: str):
             "Create a show before running a beat.",
             EMPTY_DIRECTOR_LOG,
             EMPTY_TRACE,
-            render_backend_settings(None, backend_name),
+            render_backend_settings(None, backend_name, max_new_tokens, temperature),
         )
 
-    session = apply_backend_selection(session, backend_name)
+    session = apply_backend_selection(session, backend_name, max_new_tokens, temperature)
     session = run_one_beat(session)
     return session, *render_outputs(session)
 
 
-def advance_full_act(session: TheaterSession | None, backend_name: str):
+def advance_full_act(
+    session: TheaterSession | None,
+    backend_name: str,
+    max_new_tokens: int | float,
+    temperature: int | float,
+    use_deterministic_full_act: bool,
+):
     if session is None:
         yield (
             None,
@@ -1012,24 +1084,46 @@ def advance_full_act(session: TheaterSession | None, backend_name: str):
             "Create a show before running the full act.",
             EMPTY_DIRECTOR_LOG,
             EMPTY_TRACE,
-            render_backend_settings(None, backend_name),
+            render_backend_settings(None, backend_name, max_new_tokens, temperature),
         )
         return
 
-    session = apply_backend_selection(session, backend_name)
+    session = apply_backend_selection(session, backend_name, max_new_tokens, temperature)
+    selected_backend = session.backend_name
+    deterministic_full_act = selected_backend == "openbmb" and use_deterministic_full_act
+    if deterministic_full_act:
+        session.director_log.append(
+            "OpenBMB is selected, so Run Full Act will use deterministic actor lines for this playback."
+        )
+        session.trace_events.append("full_act_openbmb_deterministic_playback")
+
     if session.beat_index >= session.max_beats:
+        if deterministic_full_act:
+            session.backend_name = "deterministic"
         session = run_one_beat(session)
+        if deterministic_full_act:
+            session.backend_name = selected_backend
         yield session, *render_outputs(session)
         return
 
     while session.beat_index < session.max_beats:
+        if deterministic_full_act:
+            session.backend_name = "deterministic"
         session = run_one_beat(session)
+        if deterministic_full_act:
+            session.backend_name = selected_backend
         yield session, *render_outputs(session)
         if session.beat_index < session.max_beats:
             sleep(PLAYBACK_DELAY_SECONDS)
 
 
-def throw_audience_prop(session: TheaterSession | None, prop_name: str, backend_name: str):
+def throw_audience_prop(
+    session: TheaterSession | None,
+    prop_name: str,
+    backend_name: str,
+    max_new_tokens: int | float,
+    temperature: int | float,
+):
     if session is None:
         return (
             None,
@@ -1037,15 +1131,21 @@ def throw_audience_prop(session: TheaterSession | None, prop_name: str, backend_
             "Create a show before throwing a prop.",
             EMPTY_DIRECTOR_LOG,
             EMPTY_TRACE,
-            render_backend_settings(None, backend_name),
+            render_backend_settings(None, backend_name, max_new_tokens, temperature),
         )
 
-    session = apply_backend_selection(session, backend_name)
+    session = apply_backend_selection(session, backend_name, max_new_tokens, temperature)
     session = throw_prop(session, prop_name)
     return session, *render_outputs(session)
 
 
-def summon_audience_actor(session: TheaterSession | None, actor_name: str, backend_name: str):
+def summon_audience_actor(
+    session: TheaterSession | None,
+    actor_name: str,
+    backend_name: str,
+    max_new_tokens: int | float,
+    temperature: int | float,
+):
     if session is None:
         return (
             None,
@@ -1053,15 +1153,20 @@ def summon_audience_actor(session: TheaterSession | None, actor_name: str, backe
             "Create a show before summoning an actor.",
             EMPTY_DIRECTOR_LOG,
             EMPTY_TRACE,
-            render_backend_settings(None, backend_name),
+            render_backend_settings(None, backend_name, max_new_tokens, temperature),
         )
 
-    session = apply_backend_selection(session, backend_name)
+    session = apply_backend_selection(session, backend_name, max_new_tokens, temperature)
     session = summon_actor(session, actor_name)
     return session, *render_outputs(session)
 
 
-def request_audience_finale(session: TheaterSession | None, backend_name: str):
+def request_audience_finale(
+    session: TheaterSession | None,
+    backend_name: str,
+    max_new_tokens: int | float,
+    temperature: int | float,
+):
     if session is None:
         return (
             None,
@@ -1069,14 +1174,43 @@ def request_audience_finale(session: TheaterSession | None, backend_name: str):
             "Create a show before requesting a finale.",
             EMPTY_DIRECTOR_LOG,
             EMPTY_TRACE,
-            render_backend_settings(None, backend_name),
+            render_backend_settings(None, backend_name, max_new_tokens, temperature),
         )
 
-    session = apply_backend_selection(session, backend_name)
+    session = apply_backend_selection(session, backend_name, max_new_tokens, temperature)
     session = request_finale(session)
     return session, *render_outputs(session)
 
 
+def warm_up_backend(
+    session: TheaterSession | None,
+    max_new_tokens: int | float,
+    temperature: int | float,
+):
+    selected_max_new_tokens = normalize_max_new_tokens(max_new_tokens)
+    selected_temperature = normalize_temperature(temperature)
+    status = warm_up_openbmb(
+        max_new_tokens=selected_max_new_tokens,
+        temperature=selected_temperature,
+    )
+    if session is not None:
+        session.backend_max_new_tokens = selected_max_new_tokens
+        session.backend_temperature = selected_temperature
+        if status.load_status == "loaded":
+            session.director_log.append(f"OpenBMB warm-up loaded {status.model_id}.")
+            session.trace_events.append(f"openbmb_warmup_loaded:{status.model_id}:latency_ms={status.latest_latency_ms}")
+        else:
+            reason = status.latest_fallback_reason or "unknown error"
+            session.director_log.append(f"OpenBMB warm-up failed: {reason}.")
+            session.trace_events.append(f"openbmb_warmup_failed:{status.model_id}:{reason}")
+    return (
+        session,
+        render_director_log(session),
+        render_trace(session),
+        render_backend_settings(session, "openbmb", selected_max_new_tokens, selected_temperature),
+    )
+
+
 with gr.Blocks(title="AI Puppet Theater") as app:
     session_state = gr.State(None)
 
@@ -1163,43 +1297,77 @@ with gr.Blocks(title="AI Puppet Theater") as app:
             label="Actor Line Backend",
             interactive=True,
         )
+        with gr.Row():
+            max_new_tokens_input = gr.Slider(
+                minimum=16,
+                maximum=160,
+                value=DEFAULT_MAX_NEW_TOKENS,
+                step=8,
+                label="Max New Tokens",
+                interactive=True,
+            )
+            temperature_input = gr.Slider(
+                minimum=0.0,
+                maximum=1.5,
+                value=DEFAULT_TEMPERATURE,
+                step=0.1,
+                label="Temperature",
+                interactive=True,
+            )
+        deterministic_full_act_input = gr.Checkbox(
+            value=True,
+            label="Use deterministic actor lines for OpenBMB full-act playback",
+            interactive=True,
+        )
+        warm_up_button = gr.Button("Warm up OpenBMB", elem_classes=["secondary-action"])
         backend_output = gr.Textbox(
             value=EMPTY_BACKEND,
             label="Model Settings",
-            lines=4,
+            lines=8,
             interactive=False,
         )
 
     create_button.click(
         create_show,
-        inputs=[premise_input, session_state, backend_select],
+        inputs=[premise_input, session_state, backend_select, max_new_tokens_input, temperature_input],
         outputs=[session_state, stage_output, transcript_output, director_output, trace_output, backend_output],
     )
     run_one_button.click(
         advance_one_beat,
-        inputs=[session_state, backend_select],
+        inputs=[session_state, backend_select, max_new_tokens_input, temperature_input],
         outputs=[session_state, stage_output, transcript_output, director_output, trace_output, backend_output],
     )
     run_full_button.click(
         advance_full_act,
-        inputs=[session_state, backend_select],
+        inputs=[
+            session_state,
+            backend_select,
+            max_new_tokens_input,
+            temperature_input,
+            deterministic_full_act_input,
+        ],
         outputs=[session_state, stage_output, transcript_output, director_output, trace_output, backend_output],
     )
     throw_prop_button.click(
         throw_audience_prop,
-        inputs=[session_state, prop_input, backend_select],
+        inputs=[session_state, prop_input, backend_select, max_new_tokens_input, temperature_input],
         outputs=[session_state, stage_output, transcript_output, director_output, trace_output, backend_output],
     )
     summon_actor_button.click(
         summon_audience_actor,
-        inputs=[session_state, actor_input, backend_select],
+        inputs=[session_state, actor_input, backend_select, max_new_tokens_input, temperature_input],
         outputs=[session_state, stage_output, transcript_output, director_output, trace_output, backend_output],
     )
     request_finale_button.click(
         request_audience_finale,
-        inputs=[session_state, backend_select],
+        inputs=[session_state, backend_select, max_new_tokens_input, temperature_input],
         outputs=[session_state, stage_output, transcript_output, director_output, trace_output, backend_output],
     )
+    warm_up_button.click(
+        warm_up_backend,
+        inputs=[session_state, max_new_tokens_input, temperature_input],
+        outputs=[session_state, director_output, trace_output, backend_output],
+    )
     reset_button.click(
         reset_show,
         outputs=[
@@ -1212,6 +1380,9 @@ with gr.Blocks(title="AI Puppet Theater") as app:
             director_output,
             trace_output,
             backend_select,
+            max_new_tokens_input,
+            temperature_input,
+            deterministic_full_act_input,
             backend_output,
         ],
     )

puppet_theater/__init__.py

@@ -5,7 +5,9 @@ from puppet_theater.backends import (
     ModelBackend,
     OpenBMBTransformersBackend,
     generate_actor_response,
+    get_backend_status,
     parse_actor_output,
+    warm_up_openbmb,
 )
 from puppet_theater.director import BEAT_ARC, run_full_act, run_one_beat
 from puppet_theater.models import Actor, ActorResponse, Beat, TheaterSession
@@ -23,10 +25,12 @@ __all__ = [
     "TheaterSession",
     "create_show_from_premise",
     "generate_actor_response",
+    "get_backend_status",
     "parse_actor_output",
     "request_finale",
     "run_full_act",
     "run_one_beat",
     "summon_actor",
     "throw_prop",
+    "warm_up_openbmb",
 ]

puppet_theater/backends.py

@@ -13,7 +13,8 @@ from puppet_theater.prompts import ACTOR_LINE_PROMPT
 
 MAX_ACTOR_LINE_CHARS = 220
 DEFAULT_OPENBMB_MODEL_ID = "openbmb/MiniCPM5-1B"
-OPENBMB_MAX_NEW_TOKENS = 112
+OPENBMB_MAX_NEW_TOKENS = 80
+OPENBMB_TEMPERATURE = 0.8
 
 
 @dataclass(frozen=True)
@@ -23,10 +24,24 @@ class BackendGeneration:
     model_id: str | None
     fallback_used: bool
     validation_status: str
+    load_status: str
     latency_ms: int | None = None
     error: str | None = None
 
 
+@dataclass(frozen=True)
+class BackendRuntimeStatus:
+    backend_name: str
+    model_id: str | None
+    load_status: str
+    latest_latency_ms: int | None = None
+    latest_validation_status: str | None = None
+    latest_fallback_used: bool | None = None
+    latest_fallback_reason: str | None = None
+    max_new_tokens: int | None = None
+    temperature: float | None = None
+
+
 class ModelBackend(ABC):
     name: str = "base"
     model_id: str | None = None
@@ -55,6 +70,7 @@ class ModelBackend(ABC):
 
 class DeterministicBackend(ModelBackend):
     name = "deterministic"
+    load_status = "loaded"
 
     def generate_actor_response(
         self,
@@ -69,13 +85,30 @@ class DeterministicBackend(ModelBackend):
 class OpenBMBTransformersBackend(ModelBackend):
     name = "openbmb"
 
-    def __init__(self, model_id: str | None = None, max_new_tokens: int = OPENBMB_MAX_NEW_TOKENS) -> None:
+    def __init__(
+        self,
+        model_id: str | None = None,
+        max_new_tokens: int = OPENBMB_MAX_NEW_TOKENS,
+        temperature: float = OPENBMB_TEMPERATURE,
+    ) -> None:
         self.model_id = model_id or os.getenv("OPENBMB_MODEL_ID", DEFAULT_OPENBMB_MODEL_ID)
         self.max_new_tokens = max_new_tokens
+        self.temperature = temperature
+        self.load_status = "unloaded"
+        self.latest_latency_ms: int | None = None
+        self.latest_validation_status: str | None = None
+        self.latest_fallback_used: bool | None = None
+        self.latest_fallback_reason: str | None = None
         self._tokenizer = None
         self._model = None
         self._torch = None
 
+    def configure(self, max_new_tokens: int | None = None, temperature: float | None = None) -> None:
+        if max_new_tokens is not None:
+            self.max_new_tokens = _clamp_int(max_new_tokens, 16, 160)
+        if temperature is not None:
+            self.temperature = _clamp_float(temperature, 0.0, 1.5)
+
     def generate_actor_response(
         self,
         session: TheaterSession,
@@ -105,22 +138,35 @@ class OpenBMBTransformersBackend(ModelBackend):
 
     def _load(self) -> None:
         if self._tokenizer is not None and self._model is not None:
+            self.load_status = "loaded"
             return
 
+        self.load_status = "loading"
         try:
             import torch
             from transformers import AutoModelForCausalLM, AutoTokenizer
         except ImportError as exc:
+            self.load_status = "error"
+            self.latest_fallback_reason = "OpenBMB backend dependencies are not installed"
             raise RuntimeError("OpenBMB backend dependencies are not installed") from exc
 
-        self._torch = torch
-        self._tokenizer = AutoTokenizer.from_pretrained(self.model_id)
-        self._model = AutoModelForCausalLM.from_pretrained(
-            self.model_id,
-            torch_dtype="auto",
-            device_map="auto",
-        )
-        self._model.eval()
+        try:
+            self._torch = torch
+            self._tokenizer = AutoTokenizer.from_pretrained(self.model_id)
+            self._model = AutoModelForCausalLM.from_pretrained(
+                self.model_id,
+                torch_dtype="auto",
+                device_map="auto",
+            )
+            self._model.eval()
+        except Exception as exc:
+            self._tokenizer = None
+            self._model = None
+            self.load_status = "error"
+            self.latest_fallback_reason = _summarize_error(exc)
+            raise
+
+        self.load_status = "loaded"
 
     def _generate_text(self, prompt: str) -> str:
         self._load()
@@ -149,14 +195,17 @@ class OpenBMBTransformersBackend(ModelBackend):
         inputs = inputs.to(model.device)
         eos_token_id = tokenizer.eos_token_id
         pad_token_id = tokenizer.pad_token_id or eos_token_id
+        do_sample = self.temperature > 0
+        generation_kwargs = {
+            "max_new_tokens": self.max_new_tokens,
+            "do_sample": do_sample,
+            "pad_token_id": pad_token_id,
+            "eos_token_id": eos_token_id,
+        }
+        if do_sample:
+            generation_kwargs["temperature"] = self.temperature
         with self._torch.inference_mode():
-            outputs = model.generate(
-                **inputs,
-                max_new_tokens=self.max_new_tokens,
-                do_sample=False,
-                pad_token_id=pad_token_id,
-                eos_token_id=eos_token_id,
-            )
+            outputs = model.generate(**inputs, **generation_kwargs)
         new_tokens = outputs[0][inputs["input_ids"].shape[-1] :]
         return tokenizer.decode(new_tokens, skip_special_tokens=True).strip()
 
@@ -183,7 +232,11 @@ def generate_actor_response(
     prop: str | None,
     backend: ModelBackend | None = None,
 ) -> BackendGeneration:
-    active_backend = backend or get_backend(session.backend_name)
+    active_backend = backend or get_backend(
+        session.backend_name,
+        max_new_tokens=session.backend_max_new_tokens,
+        temperature=session.backend_temperature,
+    )
     start_time = time.perf_counter()
     raw_output: ActorResponse | dict[str, Any] | str | None = None
     try:
@@ -203,14 +256,17 @@ def generate_actor_response(
 
     response, validation_status = parse_actor_output(raw_output)
     if response is not None:
-        return BackendGeneration(
+        generation = BackendGeneration(
             response=response,
             backend_name=active_backend.name,
             model_id=active_backend.model_id,
             fallback_used=False,
             validation_status=validation_status,
+            load_status=getattr(active_backend, "load_status", "loaded"),
             latency_ms=_elapsed_ms(start_time),
         )
+        _record_generation_status(active_backend, generation)
+        return generation
 
     try:
         repair_output = active_backend.repair_actor_response(
@@ -235,14 +291,17 @@ def generate_actor_response(
     if repair_output is not None:
         response, repair_status = parse_actor_output(repair_output)
         if response is not None:
-            return BackendGeneration(
+            generation = BackendGeneration(
                 response=response,
                 backend_name=active_backend.name,
                 model_id=active_backend.model_id,
                 fallback_used=False,
                 validation_status=f"repair_{repair_status}",
+                load_status=getattr(active_backend, "load_status", "loaded"),
                 latency_ms=_elapsed_ms(start_time),
             )
+            _record_generation_status(active_backend, generation)
+            return generation
         validation_status = f"{validation_status};repair_{repair_status}"
 
     return _fallback_generation(
@@ -256,17 +315,64 @@ def generate_actor_response(
     )
 
 
-def get_backend(backend_name: str | None) -> ModelBackend:
+def get_backend(
+    backend_name: str | None,
+    max_new_tokens: int | None = None,
+    temperature: float | None = None,
+) -> ModelBackend:
     normalized_name = (backend_name or "deterministic").strip().lower()
     if normalized_name == "openbmb":
         model_id = os.getenv("OPENBMB_MODEL_ID", DEFAULT_OPENBMB_MODEL_ID)
         cache_key = f"openbmb:{model_id}"
         if cache_key not in _BACKEND_CACHE:
-            _BACKEND_CACHE[cache_key] = OpenBMBTransformersBackend(model_id=model_id)
-        return _BACKEND_CACHE[cache_key]
+            _BACKEND_CACHE[cache_key] = OpenBMBTransformersBackend(
+                model_id=model_id,
+                max_new_tokens=max_new_tokens or OPENBMB_MAX_NEW_TOKENS,
+                temperature=temperature if temperature is not None else OPENBMB_TEMPERATURE,
+            )
+        backend = _BACKEND_CACHE[cache_key]
+        if isinstance(backend, OpenBMBTransformersBackend):
+            backend.configure(max_new_tokens=max_new_tokens, temperature=temperature)
+        return backend
     return _BACKEND_CACHE["deterministic"]
 
 
+def warm_up_openbmb(
+    max_new_tokens: int = OPENBMB_MAX_NEW_TOKENS,
+    temperature: float = OPENBMB_TEMPERATURE,
+) -> BackendRuntimeStatus:
+    backend = get_backend("openbmb", max_new_tokens=max_new_tokens, temperature=temperature)
+    if not isinstance(backend, OpenBMBTransformersBackend):
+        return get_backend_status("deterministic")
+
+    start_time = time.perf_counter()
+    try:
+        backend._load()
+        backend.latest_latency_ms = _elapsed_ms(start_time)
+        backend.latest_fallback_reason = None
+    except Exception as exc:
+        backend.latest_latency_ms = _elapsed_ms(start_time)
+        backend.latest_fallback_reason = _summarize_error(exc)
+    return get_backend_status("openbmb")
+
+
+def get_backend_status(backend_name: str | None = None) -> BackendRuntimeStatus:
+    normalized_name = (backend_name or "deterministic").strip().lower()
+    if normalized_name == "openbmb":
+        model_id = os.getenv("OPENBMB_MODEL_ID", DEFAULT_OPENBMB_MODEL_ID)
+        backend = _BACKEND_CACHE.get(f"openbmb:{model_id}")
+        if backend is None:
+            return BackendRuntimeStatus(
+                backend_name="openbmb",
+                model_id=model_id,
+                load_status="unloaded",
+                max_new_tokens=OPENBMB_MAX_NEW_TOKENS,
+                temperature=OPENBMB_TEMPERATURE,
+            )
+        return _runtime_status_from_backend(backend)
+    return _runtime_status_from_backend(_BACKEND_CACHE["deterministic"])
+
+
 def build_actor_line_prompt(
     session: TheaterSession,
     beat_type: str,
@@ -304,15 +410,18 @@ def _fallback_generation(
     error: str | None = None,
 ) -> BackendGeneration:
     fallback_response = deterministic_actor_response(session, beat_type, speaker, prop)
-    return BackendGeneration(
+    generation = BackendGeneration(
         response=fallback_response,
         backend_name=backend.name,
         model_id=backend.model_id,
         fallback_used=True,
         validation_status=validation_status,
+        load_status=getattr(backend, "load_status", "loaded"),
         latency_ms=latency_ms,
         error=error,
     )
+    _record_generation_status(backend, generation)
+    return generation
 
 
 def parse_actor_output(raw_output: ActorResponse | dict[str, Any] | str) -> tuple[ActorResponse | None, str]:
@@ -364,6 +473,39 @@ def _summarize_error(exc: Exception) -> str:
     return message[:180]
 
 
+def _clamp_int(value: int, minimum: int, maximum: int) -> int:
+    return max(minimum, min(maximum, int(value)))
+
+
+def _clamp_float(value: float, minimum: float, maximum: float) -> float:
+    return max(minimum, min(maximum, float(value)))
+
+
+def _record_generation_status(backend: ModelBackend, generation: BackendGeneration) -> None:
+    if hasattr(backend, "latest_latency_ms"):
+        backend.latest_latency_ms = generation.latency_ms
+    if hasattr(backend, "latest_validation_status"):
+        backend.latest_validation_status = generation.validation_status
+    if hasattr(backend, "latest_fallback_used"):
+        backend.latest_fallback_used = generation.fallback_used
+    if hasattr(backend, "latest_fallback_reason"):
+        backend.latest_fallback_reason = generation.error
+
+
+def _runtime_status_from_backend(backend: ModelBackend) -> BackendRuntimeStatus:
+    return BackendRuntimeStatus(
+        backend_name=backend.name,
+        model_id=backend.model_id,
+        load_status=getattr(backend, "load_status", "loaded"),
+        latest_latency_ms=getattr(backend, "latest_latency_ms", None),
+        latest_validation_status=getattr(backend, "latest_validation_status", None),
+        latest_fallback_used=getattr(backend, "latest_fallback_used", None),
+        latest_fallback_reason=getattr(backend, "latest_fallback_reason", None),
+        max_new_tokens=getattr(backend, "max_new_tokens", None),
+        temperature=getattr(backend, "temperature", None),
+    )
+
+
 def _line_for_beat(
     session: TheaterSession,
     beat_type: str,

puppet_theater/director.py

@@ -50,7 +50,7 @@ def run_one_beat(session: TheaterSession | None) -> TheaterSession | None:
         "Backend "
         f"{backend_generation.backend_name} returned actor output "
         f"({backend_generation.validation_status}, fallback={backend_generation.fallback_used}"
-        f", latency={backend_generation.latency_ms}ms)."
+        f", load_status={backend_generation.load_status}, latency={backend_generation.latency_ms}ms)."
     )
     if backend_generation.model_id:
         session.director_log.append(f"Model id: {backend_generation.model_id}.")
@@ -61,6 +61,7 @@ def run_one_beat(session: TheaterSession | None) -> TheaterSession | None:
         "backend_result:"
         f"{backend_generation.backend_name}:"
         f"model={backend_generation.model_id or 'none'}:"
+        f"load_status={backend_generation.load_status}:"
         f"fallback={backend_generation.fallback_used}:"
         f"validation={backend_generation.validation_status}:"
         f"latency_ms={backend_generation.latency_ms}"

puppet_theater/models.py

@@ -65,3 +65,5 @@ class TheaterSession:
     finale_requested: bool = False
     backend_name: str = "deterministic"
     backend_model_id: str | None = None
+    backend_max_new_tokens: int = 80
+    backend_temperature: float = 0.8

puppet_theater/session.py

@@ -27,7 +27,13 @@ def _setting_from_premise(premise: str) -> str:
     return "a pocket-sized improv stage with painted flats and a wobbly spotlight"
 
 
-def create_show_from_premise(premise: str, backend_name: str = "deterministic", backend_model_id: str | None = None) -> TheaterSession:
+def create_show_from_premise(
+    premise: str,
+    backend_name: str = "deterministic",
+    backend_model_id: str | None = None,
+    backend_max_new_tokens: int = 80,
+    backend_temperature: float = 0.8,
+) -> TheaterSession:
     cleaned_premise = _clean_premise(premise)
     show_title = _title_from_premise(cleaned_premise)
     setting = _setting_from_premise(cleaned_premise)
@@ -90,4 +96,6 @@ def create_show_from_premise(premise: str, backend_name: str = "deterministic",
         finale_requested=False,
         backend_name=active_backend,
         backend_model_id=backend_model_id,
+        backend_max_new_tokens=backend_max_new_tokens,
+        backend_temperature=backend_temperature,
     )