feat: add optional llm director

app.py

@@ -41,11 +41,13 @@ EMPTY_DIRECTOR_LOG = "No director notes yet."
 EMPTY_TRACE = "No trace events yet."
 EMPTY_BACKEND = (
     "Active backend: deterministic\n"
+    "Director mode: deterministic\n"
     "OpenBMB model id: openbmb/MiniCPM5-1B\n"
     "Model status: unloaded\n"
     "Fallback: deterministic safety path enabled"
 )
 BACKEND_CHOICES = ["deterministic", "openbmb"]
+DIRECTOR_MODE_CHOICES = ["deterministic", "openbmb"]
 OPENBMB_MODEL_ID = os.getenv("OPENBMB_MODEL_ID", DEFAULT_OPENBMB_MODEL_ID)
 DEFAULT_MAX_NEW_TOKENS = 80
 DEFAULT_TEMPERATURE = 0.8
@@ -1588,6 +1590,10 @@ def normalize_backend_name(backend_name: str | None) -> str:
     return backend_name if backend_name in BACKEND_CHOICES else "deterministic"
 
 
+def normalize_director_mode(director_mode: str | None) -> str:
+    return director_mode if director_mode in DIRECTOR_MODE_CHOICES else "deterministic"
+
+
 def normalize_max_new_tokens(max_new_tokens: int | float | None) -> int:
     if max_new_tokens is None:
         return DEFAULT_MAX_NEW_TOKENS
@@ -1603,6 +1609,7 @@ def normalize_temperature(temperature: int | float | None) -> float:
 def apply_backend_selection(
     session: TheaterSession | None,
     backend_name: str | None,
+    director_mode: str | None,
     max_new_tokens: int | float | None = None,
     temperature: int | float | None = None,
 ) -> TheaterSession | None:
@@ -1610,6 +1617,7 @@ def apply_backend_selection(
         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.director_mode = normalize_director_mode(director_mode)
     session.backend_max_new_tokens = normalize_max_new_tokens(max_new_tokens)
     session.backend_temperature = normalize_temperature(temperature)
     return session
@@ -1618,13 +1626,16 @@ def apply_backend_selection(
 def render_backend_settings(
     session: TheaterSession | None,
     backend_name: str | None = None,
+    director_mode: str | None = None,
     max_new_tokens: int | float | None = None,
     temperature: int | float | None = None,
 ) -> str:
     selected_backend = normalize_backend_name(backend_name)
+    selected_director_mode = normalize_director_mode(director_mode)
     active_backend = session.backend_name if session is not None else selected_backend
+    active_director_mode = session.director_mode if session is not None else selected_director_mode
     model_id = session.backend_model_id if session is not None else None
-    if active_backend == "openbmb":
+    if active_backend == "openbmb" or active_director_mode == "openbmb":
         model_id = model_id or OPENBMB_MODEL_ID
     status = get_backend_status(active_backend)
     openbmb_status = get_backend_status("openbmb")
@@ -1638,7 +1649,9 @@ def render_backend_settings(
     fallback_reason = status.latest_fallback_reason or "none"
     return (
         f"Active backend: {active_backend}\n"
-        "Available backends: deterministic, openbmb\n"
+        f"Director mode: {active_director_mode}\n"
+        "Available actor backends: deterministic, openbmb\n"
+        "Available director modes: 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"
@@ -1663,11 +1676,13 @@ def create_show(
     premise: str,
     session: TheaterSession | None,
     backend_name: str,
+    director_mode: str,
     max_new_tokens: int | float,
     temperature: int | float,
 ):
     premise = premise.strip()
     selected_backend = normalize_backend_name(backend_name)
+    selected_director_mode = normalize_director_mode(director_mode)
     selected_max_new_tokens = normalize_max_new_tokens(max_new_tokens)
     selected_temperature = normalize_temperature(temperature)
     if not premise:
@@ -1677,7 +1692,13 @@ def create_show(
             "No premise yet. Add a premise to raise the curtain.",
             EMPTY_DIRECTOR_LOG,
             EMPTY_TRACE,
-            render_backend_settings(None, selected_backend, selected_max_new_tokens, selected_temperature),
+            render_backend_settings(
+                None,
+                selected_backend,
+                selected_director_mode,
+                selected_max_new_tokens,
+                selected_temperature,
+            ),
         )
 
     session = create_show_from_premise(
@@ -1686,6 +1707,7 @@ def create_show(
         backend_model_id=OPENBMB_MODEL_ID if selected_backend == "openbmb" else None,
         backend_max_new_tokens=selected_max_new_tokens,
         backend_temperature=selected_temperature,
+        director_mode=selected_director_mode,
     )
     return session, *render_outputs(session)
 
@@ -1701,6 +1723,7 @@ def reset_show():
         EMPTY_DIRECTOR_LOG,
         EMPTY_TRACE,
         "deterministic",
+        "deterministic",
         DEFAULT_MAX_NEW_TOKENS,
         DEFAULT_TEMPERATURE,
         True,
@@ -1711,6 +1734,7 @@ def reset_show():
 def advance_one_beat(
     session: TheaterSession | None,
     backend_name: str,
+    director_mode: str,
     max_new_tokens: int | float,
     temperature: int | float,
 ):
@@ -1721,10 +1745,10 @@ def advance_one_beat(
             "Create a show before running a beat.",
             EMPTY_DIRECTOR_LOG,
             EMPTY_TRACE,
-            render_backend_settings(None, backend_name, max_new_tokens, temperature),
+            render_backend_settings(None, backend_name, director_mode, max_new_tokens, temperature),
         )
 
-    session = apply_backend_selection(session, backend_name, max_new_tokens, temperature)
+    session = apply_backend_selection(session, backend_name, director_mode, max_new_tokens, temperature)
     session = run_one_beat(session)
     return session, *render_outputs(session)
 
@@ -1732,6 +1756,7 @@ def advance_one_beat(
 def advance_full_act(
     session: TheaterSession | None,
     backend_name: str,
+    director_mode: str,
     max_new_tokens: int | float,
     temperature: int | float,
     use_deterministic_full_act: bool,
@@ -1743,34 +1768,42 @@ def advance_full_act(
             "Create a show before running the full act.",
             EMPTY_DIRECTOR_LOG,
             EMPTY_TRACE,
-            render_backend_settings(None, backend_name, max_new_tokens, temperature),
+            render_backend_settings(None, backend_name, director_mode, max_new_tokens, temperature),
         )
         return
 
-    session = apply_backend_selection(session, backend_name, max_new_tokens, temperature)
+    session = apply_backend_selection(session, backend_name, director_mode, max_new_tokens, temperature)
     selected_backend = session.backend_name
-    deterministic_full_act = selected_backend == "openbmb" and use_deterministic_full_act
+    selected_director_mode = session.director_mode
+    deterministic_full_act = (
+        (selected_backend == "openbmb" or selected_director_mode == "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."
+            "OpenBMB is selected, so Run Full Act will use deterministic playback for this run."
         )
         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.director_mode = "deterministic"
         session = run_one_beat(session)
         if deterministic_full_act:
             session.backend_name = selected_backend
+            session.director_mode = selected_director_mode
         yield session, *render_outputs(session)
         return
 
     while session.beat_index < session.max_beats:
         if deterministic_full_act:
             session.backend_name = "deterministic"
+            session.director_mode = "deterministic"
         session = run_one_beat(session)
         if deterministic_full_act:
             session.backend_name = selected_backend
+            session.director_mode = selected_director_mode
         yield session, *render_outputs(session)
         if session.beat_index < session.max_beats:
             sleep(PLAYBACK_DELAY_SECONDS)
@@ -1780,6 +1813,7 @@ def throw_audience_prop(
     session: TheaterSession | None,
     prop_name: str,
     backend_name: str,
+    director_mode: str,
     max_new_tokens: int | float,
     temperature: int | float,
 ):
@@ -1790,10 +1824,10 @@ def throw_audience_prop(
             "Create a show before throwing a prop.",
             EMPTY_DIRECTOR_LOG,
             EMPTY_TRACE,
-            render_backend_settings(None, backend_name, max_new_tokens, temperature),
+            render_backend_settings(None, backend_name, director_mode, max_new_tokens, temperature),
         )
 
-    session = apply_backend_selection(session, backend_name, max_new_tokens, temperature)
+    session = apply_backend_selection(session, backend_name, director_mode, max_new_tokens, temperature)
     session = throw_prop(session, prop_name)
     return session, *render_outputs(session)
 
@@ -1802,6 +1836,7 @@ def summon_audience_actor(
     session: TheaterSession | None,
     actor_name: str,
     backend_name: str,
+    director_mode: str,
     max_new_tokens: int | float,
     temperature: int | float,
 ):
@@ -1812,10 +1847,10 @@ def summon_audience_actor(
             "Create a show before summoning an actor.",
             EMPTY_DIRECTOR_LOG,
             EMPTY_TRACE,
-            render_backend_settings(None, backend_name, max_new_tokens, temperature),
+            render_backend_settings(None, backend_name, director_mode, max_new_tokens, temperature),
         )
 
-    session = apply_backend_selection(session, backend_name, max_new_tokens, temperature)
+    session = apply_backend_selection(session, backend_name, director_mode, max_new_tokens, temperature)
     session = summon_actor(session, actor_name)
     return session, *render_outputs(session)
 
@@ -1823,6 +1858,7 @@ def summon_audience_actor(
 def request_audience_finale(
     session: TheaterSession | None,
     backend_name: str,
+    director_mode: str,
     max_new_tokens: int | float,
     temperature: int | float,
 ):
@@ -1833,10 +1869,10 @@ def request_audience_finale(
             "Create a show before requesting a finale.",
             EMPTY_DIRECTOR_LOG,
             EMPTY_TRACE,
-            render_backend_settings(None, backend_name, max_new_tokens, temperature),
+            render_backend_settings(None, backend_name, director_mode, max_new_tokens, temperature),
         )
 
-    session = apply_backend_selection(session, backend_name, max_new_tokens, temperature)
+    session = apply_backend_selection(session, backend_name, director_mode, max_new_tokens, temperature)
     session = request_finale(session)
     return session, *render_outputs(session)
 
@@ -1866,7 +1902,13 @@ def warm_up_backend(
         session,
         render_director_log(session),
         render_trace(session),
-        render_backend_settings(session, "openbmb", selected_max_new_tokens, selected_temperature),
+        render_backend_settings(
+            session,
+            "openbmb",
+            session.director_mode if session is not None else "deterministic",
+            selected_max_new_tokens,
+            selected_temperature,
+        ),
     )
 
 
@@ -1962,6 +2004,12 @@ with gr.Blocks(title="AI Puppet Theater") as app:
             label="Actor Line Backend",
             interactive=True,
         )
+        director_mode_select = gr.Dropdown(
+            choices=DIRECTOR_MODE_CHOICES,
+            value="deterministic",
+            label="Director Mode",
+            interactive=True,
+        )
         with gr.Row():
             max_new_tokens_input = gr.Slider(
                 minimum=16,
@@ -1981,7 +2029,7 @@ with gr.Blocks(title="AI Puppet Theater") as app:
             )
         deterministic_full_act_input = gr.Checkbox(
             value=True,
-            label="Use deterministic actor lines for OpenBMB full-act playback",
+            label="Use deterministic playback for OpenBMB full-act runs",
             interactive=True,
         )
         warm_up_button = gr.Button("Warm up OpenBMB", elem_classes=["cue-action"])
@@ -1995,12 +2043,25 @@ with gr.Blocks(title="AI Puppet Theater") as app:
 
     create_button.click(
         create_show,
-        inputs=[premise_input, session_state, backend_select, max_new_tokens_input, temperature_input],
+        inputs=[
+            premise_input,
+            session_state,
+            backend_select,
+            director_mode_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, max_new_tokens_input, temperature_input],
+        inputs=[
+            session_state,
+            backend_select,
+            director_mode_select,
+            max_new_tokens_input,
+            temperature_input,
+        ],
         outputs=[session_state, stage_output, transcript_output, director_output, trace_output, backend_output],
     )
     run_full_button.click(
@@ -2008,6 +2069,7 @@ with gr.Blocks(title="AI Puppet Theater") as app:
         inputs=[
             session_state,
             backend_select,
+            director_mode_select,
             max_new_tokens_input,
             temperature_input,
             deterministic_full_act_input,
@@ -2016,17 +2078,37 @@ with gr.Blocks(title="AI Puppet Theater") as app:
     )
     throw_prop_button.click(
         throw_audience_prop,
-        inputs=[session_state, prop_input, backend_select, max_new_tokens_input, temperature_input],
+        inputs=[
+            session_state,
+            prop_input,
+            backend_select,
+            director_mode_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, max_new_tokens_input, temperature_input],
+        inputs=[
+            session_state,
+            actor_input,
+            backend_select,
+            director_mode_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, max_new_tokens_input, temperature_input],
+        inputs=[
+            session_state,
+            backend_select,
+            director_mode_select,
+            max_new_tokens_input,
+            temperature_input,
+        ],
         outputs=[session_state, stage_output, transcript_output, director_output, trace_output, backend_output],
     )
     warm_up_button.click(
@@ -2046,6 +2128,7 @@ with gr.Blocks(title="AI Puppet Theater") as app:
             director_output,
             trace_output,
             backend_select,
+            director_mode_select,
             max_new_tokens_input,
             temperature_input,
             deterministic_full_act_input,

puppet_theater/__init__.py

@@ -9,7 +9,15 @@ from puppet_theater.backends import (
     parse_actor_output,
     warm_up_openbmb,
 )
-from puppet_theater.director import BEAT_ARC, DirectorPolicy, run_full_act, run_one_beat
+from puppet_theater.director import (
+    BEAT_ARC,
+    DirectorGeneration,
+    DirectorPolicy,
+    OpenBMBDirectorPolicy,
+    choose_director_decision,
+    run_full_act,
+    run_one_beat,
+)
 from puppet_theater.models import Actor, ActorResponse, Beat, DirectorDecision, TheaterSession
 from puppet_theater.session import create_show_from_premise
 
@@ -21,11 +29,14 @@ __all__ = [
     "DEFAULT_OPENBMB_MODEL_ID",
     "DeterministicBackend",
     "DirectorDecision",
+    "DirectorGeneration",
     "DirectorPolicy",
     "ModelBackend",
+    "OpenBMBDirectorPolicy",
     "OpenBMBTransformersBackend",
     "TheaterSession",
     "create_show_from_premise",
+    "choose_director_decision",
     "generate_actor_response",
     "get_backend_status",
     "parse_actor_output",

puppet_theater/director.py

@@ -1,7 +1,18 @@
 from collections import Counter
+from dataclasses import dataclass
+import json
+import time
 
-from puppet_theater.backends import generate_actor_response
+from pydantic import ValidationError
+
+from puppet_theater.backends import (
+    DEFAULT_OPENBMB_MODEL_ID,
+    OpenBMBTransformersBackend,
+    generate_actor_response,
+    get_backend,
+)
 from puppet_theater.models import Actor, Beat, DirectorDecision, TheaterSession
+from puppet_theater.prompts import DIRECTOR_DECISION_PROMPT
 
 
 BEAT_ARC = [
@@ -14,6 +25,18 @@ BEAT_ARC = [
 ]
 
 
+@dataclass(frozen=True)
+class DirectorGeneration:
+    decision: DirectorDecision
+    director_mode: str
+    model_id: str | None
+    validation_status: str
+    fallback_used: bool
+    reason_summary: str
+    latency_ms: int | None = None
+    error: str | None = None
+
+
 class DirectorPolicy:
     def decide(self, session: TheaterSession) -> DirectorDecision:
         if session.finale_requested or session.beat_index >= session.max_beats - 1:
@@ -100,6 +123,109 @@ class DirectorPolicy:
         }[beat_type]
 
 
+class OpenBMBDirectorPolicy:
+    def __init__(self, fallback_policy: DirectorPolicy | None = None) -> None:
+        self.fallback_policy = fallback_policy or DirectorPolicy()
+
+    def decide(self, session: TheaterSession) -> DirectorGeneration:
+        start_time = time.perf_counter()
+        backend = get_backend(
+            "openbmb",
+            max_new_tokens=session.backend_max_new_tokens,
+            temperature=session.backend_temperature,
+        )
+        if not isinstance(backend, OpenBMBTransformersBackend):
+            return self._fallback(session, "backend_unavailable", start_time)
+
+        prompt = build_director_prompt(session)
+        try:
+            raw_output = backend._generate_text(prompt)
+        except Exception as exc:
+            return self._fallback(session, "backend_error", start_time, _summarize_error(exc), backend.model_id)
+
+        decision, validation_status = parse_director_decision(raw_output, session)
+        if decision is not None:
+            return DirectorGeneration(
+                decision=decision,
+                director_mode="openbmb",
+                model_id=backend.model_id,
+                validation_status=validation_status,
+                fallback_used=False,
+                reason_summary=decision.reason_summary,
+                latency_ms=_elapsed_ms(start_time),
+            )
+
+        repair_prompt = (
+            f"{prompt}\n\nPrevious output failed validation with status {validation_status}.\n"
+            "Return only valid JSON matching the required schema. No markdown. No extra keys.\n"
+            f"Previous output: {raw_output}"
+        )
+        try:
+            repair_output = backend._generate_text(repair_prompt)
+        except Exception as exc:
+            return self._fallback(
+                session,
+                f"{validation_status};repair_backend_error",
+                start_time,
+                _summarize_error(exc),
+                backend.model_id,
+            )
+
+        decision, repair_status = parse_director_decision(repair_output, session)
+        if decision is not None:
+            return DirectorGeneration(
+                decision=decision,
+                director_mode="openbmb",
+                model_id=backend.model_id,
+                validation_status=f"repair_{repair_status}",
+                fallback_used=False,
+                reason_summary=decision.reason_summary,
+                latency_ms=_elapsed_ms(start_time),
+            )
+
+        return self._fallback(
+            session,
+            f"{validation_status};repair_{repair_status}",
+            start_time,
+            model_id=backend.model_id,
+        )
+
+    def _fallback(
+        self,
+        session: TheaterSession,
+        validation_status: str,
+        start_time: float,
+        error: str | None = None,
+        model_id: str | None = None,
+    ) -> DirectorGeneration:
+        decision = self.fallback_policy.decide(session)
+        return DirectorGeneration(
+            decision=decision,
+            director_mode="openbmb",
+            model_id=model_id or DEFAULT_OPENBMB_MODEL_ID,
+            validation_status=validation_status,
+            fallback_used=True,
+            reason_summary=decision.reason_summary,
+            latency_ms=_elapsed_ms(start_time),
+            error=error,
+        )
+
+
+def choose_director_decision(session: TheaterSession) -> DirectorGeneration:
+    if session.director_mode == "openbmb":
+        return OpenBMBDirectorPolicy().decide(session)
+    decision = DirectorPolicy().decide(session)
+    return DirectorGeneration(
+        decision=decision,
+        director_mode="deterministic",
+        model_id=None,
+        validation_status="valid",
+        fallback_used=False,
+        reason_summary=decision.reason_summary,
+        latency_ms=0,
+    )
+
+
 def run_one_beat(session: TheaterSession | None) -> TheaterSession | None:
     if session is None:
         return None
@@ -109,7 +235,8 @@ def run_one_beat(session: TheaterSession | None) -> TheaterSession | None:
         session.trace_events.append("beat_skipped:curtain_already_fallen")
         return session
 
-    decision = DirectorPolicy().decide(session)
+    director_generation = choose_director_decision(session)
+    decision = director_generation.decision
     speaker = _actor_by_name(session, decision.next_speaker)
     prop = session.latest_prop if decision.uses_prop else None
     if prop is not None:
@@ -119,14 +246,32 @@ def run_one_beat(session: TheaterSession | None) -> TheaterSession | None:
         "Director decision: "
         f"{decision.beat_type} for {speaker.name}; {decision.reason_summary}"
     )
+    session.director_log.append(
+        "Director mode "
+        f"{director_generation.director_mode} "
+        f"({director_generation.validation_status}, fallback={director_generation.fallback_used}, "
+        f"latency={director_generation.latency_ms}ms)."
+    )
+    if director_generation.model_id:
+        session.director_log.append(f"Director model id: {director_generation.model_id}.")
+    if director_generation.error:
+        session.director_log.append(f"Director fallback reason: {director_generation.error}.")
     session.trace_events.append(
         "director_decision:"
+        f"mode={director_generation.director_mode}:"
         f"speaker={speaker.name}:"
         f"beat={decision.beat_type}:"
         f"uses_prop={decision.uses_prop}:"
         f"reveal_secret={decision.reveal_secret}:"
-        f"should_end={decision.should_end_scene}"
+        f"should_end={decision.should_end_scene}:"
+        f"validation={director_generation.validation_status}:"
+        f"fallback={director_generation.fallback_used}:"
+        f"model={director_generation.model_id or 'none'}:"
+        f"latency_ms={director_generation.latency_ms}:"
+        f"reason={_trace_text(director_generation.reason_summary)}"
     )
+    if director_generation.fallback_used:
+        session.trace_events.append(f"director_fallback_used:{director_generation.validation_status}")
 
     backend_generation = generate_actor_response(session, decision, speaker, prop)
     session.beat_index += 1
@@ -204,3 +349,108 @@ def _actor_by_name(session: TheaterSession, actor_name: str) -> Actor:
         if actor.name == actor_name:
             return actor
     return session.actors[session.beat_index % len(session.actors)]
+
+
+def build_director_prompt(session: TheaterSession) -> str:
+    actor_profiles = "\n".join(
+        "- "
+        f"{actor.name}: goal={actor.goal}; style={actor.speaking_style}; "
+        f"secret_available={session.beat_index >= 2}"
+        for actor in session.actors
+    )
+    recent_transcript = "\n".join(
+        f"{beat.speaker}: {beat.line}" for beat in session.transcript[-4:]
+    ) or "No lines yet."
+    summoned_actors = ", ".join(actor.name for actor in session.actors[3:]) or "None"
+    return DIRECTOR_DECISION_PROMPT.format(
+        show_title=session.show_title,
+        premise=session.premise,
+        setting=session.setting,
+        beat_index=session.beat_index,
+        max_beats=session.max_beats,
+        allowed_beat_types=", ".join(BEAT_ARC),
+        actor_profiles=actor_profiles,
+        recent_transcript=recent_transcript,
+        audience_action=session.latest_audience_action or "None",
+        props=", ".join(session.props) or "None",
+        latest_prop=session.latest_prop or "None",
+        summoned_actors=summoned_actors,
+        finale_requested=session.finale_requested,
+    )
+
+
+def parse_director_decision(raw_output: object, session: TheaterSession) -> tuple[DirectorDecision | None, str]:
+    parsed = _coerce_director_output(raw_output)
+    if parsed is None:
+        return None, "invalid_schema"
+    if "speaker_name" in parsed and "next_speaker" not in parsed:
+        parsed["next_speaker"] = parsed["speaker_name"]
+    try:
+        decision = DirectorDecision.model_validate(parsed)
+    except ValidationError:
+        return None, "invalid_required_fields"
+    return validate_director_decision(decision, session)
+
+
+def validate_director_decision(decision: DirectorDecision, session: TheaterSession) -> tuple[DirectorDecision | None, str]:
+    actor_names = {actor.name for actor in session.actors}
+    if decision.next_speaker not in actor_names:
+        return None, "invalid_speaker"
+    if decision.beat_type not in BEAT_ARC:
+        return None, "invalid_beat_type"
+    if len(decision.instruction) > 240 or len(decision.reason_summary) > 240:
+        return None, "invalid_too_long"
+
+    update: dict[str, object] = {}
+    if session.finale_requested or session.beat_index >= session.max_beats - 1:
+        update["beat_type"] = "finale"
+        update["should_end_scene"] = True
+        update["stage_effect"] = "curtain_fall"
+    elif decision.should_end_scene and session.beat_index < session.max_beats - 2:
+        update["should_end_scene"] = False
+    if decision.uses_prop and session.latest_prop is None:
+        update["uses_prop"] = False
+    if decision.beat_type == "secret_reveal":
+        update["reveal_secret"] = True
+
+    if update:
+        decision = decision.model_copy(update=update)
+    return decision, "valid"
+
+
+def _coerce_director_output(raw_output: object) -> dict[str, object] | None:
+    if isinstance(raw_output, DirectorDecision):
+        return raw_output.model_dump()
+    if isinstance(raw_output, dict):
+        return raw_output
+    if isinstance(raw_output, str):
+        text = raw_output.strip()
+        if not text:
+            return None
+        if text.startswith("```"):
+            text = text.strip("`")
+            if "\n" in text:
+                text = text.split("\n", maxsplit=1)[1]
+        start = text.find("{")
+        end = text.rfind("}")
+        if start != -1 and end != -1 and end > start:
+            text = text[start : end + 1]
+        try:
+            decoded = json.loads(text)
+        except json.JSONDecodeError:
+            return None
+        return decoded if isinstance(decoded, dict) else None
+    return None
+
+
+def _elapsed_ms(start_time: float) -> int:
+    return round((time.perf_counter() - start_time) * 1000)
+
+
+def _summarize_error(exc: Exception) -> str:
+    message = " ".join(str(exc).split()) or exc.__class__.__name__
+    return message[:180]
+
+
+def _trace_text(value: str) -> str:
+    return " ".join(value.split()).replace(":", "-")[:140]

puppet_theater/models.py

@@ -57,6 +57,11 @@ class DirectorDecision(BaseModel):
             raise ValueError("field must not be empty")
         return cleaned
 
+    @field_validator("instruction", "reason_summary")
+    @classmethod
+    def keep_brief(cls, value: str) -> str:
+        return value[:240].rstrip()
+
 
 @dataclass
 class Actor:
@@ -98,5 +103,6 @@ class TheaterSession:
     backend_model_id: str | None = None
     backend_max_new_tokens: int = 80
     backend_temperature: float = 0.8
+    director_mode: str = "deterministic"
     # One-shot: show opening-curtain animation on the first stage render after create.
     play_opening_curtain: bool = False

puppet_theater/prompts.py

@@ -28,18 +28,28 @@ Choose the next beat for a short puppet scene. Keep the scene tight, rotate spea
 respect finale requests, and avoid exposing actor secrets unless the beat calls for it.
 
 Return only JSON with these fields:
+- next_speaker
 - beat_type
-- speaker_name
+- instruction
+- stage_effect
+- uses_prop
+- reveal_secret
 - reason_summary
-- should_end
+- should_end_scene
 
 Show title: {show_title}
 Premise: {premise}
+Setting: {setting}
 Current beat: {beat_index}
 Maximum beats: {max_beats}
-Available actors: {actor_names}
+Allowed beat types: {allowed_beat_types}
+Available actors:
+{actor_profiles}
 Recent transcript: {recent_transcript}
 Audience action: {audience_action}
+Props on stage: {props}
+Latest prop: {latest_prop}
+Summoned actors: {summoned_actors}
 Finale requested: {finale_requested}
 """
 

puppet_theater/session.py

@@ -33,6 +33,7 @@ def create_show_from_premise(
     backend_model_id: str | None = None,
     backend_max_new_tokens: int = 80,
     backend_temperature: float = 0.8,
+    director_mode: str = "deterministic",
 ) -> TheaterSession:
     cleaned_premise = _clean_premise(premise)
     show_title = _title_from_premise(cleaned_premise)
@@ -66,10 +67,12 @@ def create_show_from_premise(
     ]
 
     active_backend = backend_name if backend_name in {"deterministic", "openbmb"} else "deterministic"
+    active_director_mode = director_mode if director_mode in {"deterministic", "openbmb"} else "deterministic"
     model_note = f" ({backend_model_id})" if backend_model_id else ""
     director_log = [
         "Director created a deterministic six-beat show plan.",
         f"Active backend: {active_backend}{model_note}.",
+        f"Director mode: {active_director_mode}.",
         f"Setting selected: {setting}.",
         "Three puppet actors are waiting for the first beat.",
     ]
@@ -78,6 +81,7 @@ def create_show_from_premise(
         "actors_created:3",
         "director_plan_created",
         f"backend_active:{active_backend}",
+        f"director_mode_active:{active_director_mode}",
     ]
 
     return TheaterSession(
@@ -98,5 +102,6 @@ def create_show_from_premise(
         backend_model_id=backend_model_id,
         backend_max_new_tokens=backend_max_new_tokens,
         backend_temperature=backend_temperature,
+        director_mode=active_director_mode,
         play_opening_curtain=True,
     )