feat: add director policy

puppet_theater/__init__.py

@@ -9,8 +9,8 @@ from puppet_theater.backends import (
     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
+from puppet_theater.director import BEAT_ARC, DirectorPolicy, 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
 
 __all__ = [
@@ -20,6 +20,8 @@ __all__ = [
     "Beat",
     "DEFAULT_OPENBMB_MODEL_ID",
     "DeterministicBackend",
+    "DirectorDecision",
+    "DirectorPolicy",
     "ModelBackend",
     "OpenBMBTransformersBackend",
     "TheaterSession",

puppet_theater/backends.py

@@ -7,7 +7,7 @@ from typing import Any
 
 from pydantic import ValidationError
 
-from puppet_theater.models import Actor, ActorResponse, TheaterSession
+from puppet_theater.models import Actor, ActorResponse, DirectorDecision, TheaterSession
 from puppet_theater.prompts import ACTOR_LINE_PROMPT
 
 
@@ -50,7 +50,7 @@ class ModelBackend(ABC):
     def generate_actor_response(
         self,
         session: TheaterSession,
-        beat_type: str,
+        decision: DirectorDecision,
         speaker: Actor,
         prop: str | None,
     ) -> ActorResponse | dict[str, Any] | str:
@@ -59,7 +59,7 @@ class ModelBackend(ABC):
     def repair_actor_response(
         self,
         session: TheaterSession,
-        beat_type: str,
+        decision: DirectorDecision,
         speaker: Actor,
         prop: str | None,
         invalid_output: ActorResponse | dict[str, Any] | str,
@@ -75,11 +75,11 @@ class DeterministicBackend(ModelBackend):
     def generate_actor_response(
         self,
         session: TheaterSession,
-        beat_type: str,
+        decision: DirectorDecision,
         speaker: Actor,
         prop: str | None,
     ) -> ActorResponse:
-        return deterministic_actor_response(session, beat_type, speaker, prop)
+        return deterministic_actor_response(session, decision, speaker, prop)
 
 
 class OpenBMBTransformersBackend(ModelBackend):
@@ -112,23 +112,23 @@ class OpenBMBTransformersBackend(ModelBackend):
     def generate_actor_response(
         self,
         session: TheaterSession,
-        beat_type: str,
+        decision: DirectorDecision,
         speaker: Actor,
         prop: str | None,
     ) -> str:
-        prompt = build_actor_line_prompt(session, beat_type, speaker, prop)
+        prompt = build_actor_line_prompt(session, decision, speaker, prop)
         return self._generate_text(prompt)
 
     def repair_actor_response(
         self,
         session: TheaterSession,
-        beat_type: str,
+        decision: DirectorDecision,
         speaker: Actor,
         prop: str | None,
         invalid_output: ActorResponse | dict[str, Any] | str,
         validation_status: str,
     ) -> str | None:
-        prompt = build_actor_line_prompt(session, beat_type, speaker, prop)
+        prompt = build_actor_line_prompt(session, decision, speaker, prop)
         repair_prompt = (
             f"{prompt}\n\nThe previous output failed validation with status {validation_status}.\n"
             "Return only valid compact JSON. Do not include markdown, commentary, or extra keys.\n"
@@ -212,22 +212,22 @@ class OpenBMBTransformersBackend(ModelBackend):
 
 def deterministic_actor_response(
     session: TheaterSession,
-    beat_type: str,
+    decision: DirectorDecision,
     speaker: Actor,
     prop: str | None,
 ) -> ActorResponse:
     return ActorResponse(
-        line=_line_for_beat(session, beat_type, speaker, prop),
-        emotion=_emotion_for_beat(beat_type),
-        gesture=_gesture_for_beat(beat_type),
-        stage_effect=_effect_for_beat(beat_type),
+        line=_line_for_beat(session, decision, speaker, prop),
+        emotion=_emotion_for_beat(decision.beat_type),
+        gesture=_gesture_for_beat(decision.beat_type),
+        stage_effect=decision.stage_effect or _effect_for_beat(decision.beat_type),
         tool_request=None,
     )
 
 
 def generate_actor_response(
     session: TheaterSession,
-    beat_type: str,
+    decision: DirectorDecision,
     speaker: Actor,
     prop: str | None,
     backend: ModelBackend | None = None,
@@ -240,12 +240,12 @@ def generate_actor_response(
     start_time = time.perf_counter()
     raw_output: ActorResponse | dict[str, Any] | str | None = None
     try:
-        raw_output = active_backend.generate_actor_response(session, beat_type, speaker, prop)
+        raw_output = active_backend.generate_actor_response(session, decision, speaker, prop)
     except Exception as exc:
         latency_ms = _elapsed_ms(start_time)
         return _fallback_generation(
             session=session,
-            beat_type=beat_type,
+            decision=decision,
             speaker=speaker,
             prop=prop,
             backend=active_backend,
@@ -271,7 +271,7 @@ def generate_actor_response(
     try:
         repair_output = active_backend.repair_actor_response(
             session=session,
-            beat_type=beat_type,
+            decision=decision,
             speaker=speaker,
             prop=prop,
             invalid_output=raw_output,
@@ -280,7 +280,7 @@ def generate_actor_response(
     except Exception as exc:
         return _fallback_generation(
             session=session,
-            beat_type=beat_type,
+            decision=decision,
             speaker=speaker,
             prop=prop,
             backend=active_backend,
@@ -306,7 +306,7 @@ def generate_actor_response(
 
     return _fallback_generation(
         session=session,
-        beat_type=beat_type,
+        decision=decision,
         speaker=speaker,
         prop=prop,
         backend=active_backend,
@@ -375,7 +375,7 @@ def get_backend_status(backend_name: str | None = None) -> BackendRuntimeStatus:
 
 def build_actor_line_prompt(
     session: TheaterSession,
-    beat_type: str,
+    decision: DirectorDecision,
     speaker: Actor,
     prop: str | None,
 ) -> str:
@@ -386,12 +386,15 @@ def build_actor_line_prompt(
         show_title=session.show_title,
         premise=session.premise,
         setting=session.setting,
-        beat_type=beat_type,
+        beat_type=decision.beat_type,
         speaker_name=speaker.name,
         speaker_goal=speaker.goal,
         speaker_style=speaker.speaking_style,
         audience_action=session.latest_audience_action or "None",
         latest_prop=prop or session.latest_prop or "None",
+        director_instruction=decision.instruction,
+        reveal_secret=decision.reveal_secret,
+        stage_effect=decision.stage_effect,
     )
     return (
         f"{prompt}\nRecent transcript:\n{recent_transcript}\n\n"
@@ -401,7 +404,7 @@ def build_actor_line_prompt(
 
 def _fallback_generation(
     session: TheaterSession,
-    beat_type: str,
+    decision: DirectorDecision,
     speaker: Actor,
     prop: str | None,
     backend: ModelBackend,
@@ -409,7 +412,7 @@ def _fallback_generation(
     latency_ms: int | None,
     error: str | None = None,
 ) -> BackendGeneration:
-    fallback_response = deterministic_actor_response(session, beat_type, speaker, prop)
+    fallback_response = deterministic_actor_response(session, decision, speaker, prop)
     generation = BackendGeneration(
         response=fallback_response,
         backend_name=backend.name,
@@ -508,12 +511,13 @@ def _runtime_status_from_backend(backend: ModelBackend) -> BackendRuntimeStatus:
 
 def _line_for_beat(
     session: TheaterSession,
-    beat_type: str,
+    decision: DirectorDecision,
     speaker: Actor,
     prop: str | None,
 ) -> str:
     if prop is not None:
         return f"I shall use this {prop} as evidence, a prop, and possibly a tiny emotional support object."
+    beat_type = decision.beat_type
     if beat_type == "setup":
         return f"I see it clearly: {session.premise}, and somehow I am in charge."
     if beat_type == "denial_or_contradiction":
@@ -521,7 +525,9 @@ def _line_for_beat(
     if beat_type == "evidence_or_prop":
         return "I found a prop with fingerprints, glitter, and a very dramatic attitude."
     if beat_type == "secret_reveal":
-        return f"I confess: {speaker.secret}"
+        if decision.reveal_secret:
+            return f"I confess: {speaker.secret}"
+        return "I nearly confessed something, but the spotlight blinked and I lost my nerve."
     if beat_type == "chaos_or_intervention":
         return "The audience has interrupted with imaginary confetti, so everyone must panic gracefully."
     return "Curtain call! We solved nothing, learned everything, and bowed before the wobble got worse."

puppet_theater/director.py

@@ -1,5 +1,7 @@
+from collections import Counter
+
 from puppet_theater.backends import generate_actor_response
-from puppet_theater.models import Beat, TheaterSession
+from puppet_theater.models import Actor, Beat, DirectorDecision, TheaterSession
 
 
 BEAT_ARC = [
@@ -12,6 +14,92 @@ BEAT_ARC = [
 ]
 
 
+class DirectorPolicy:
+    def decide(self, session: TheaterSession) -> DirectorDecision:
+        if session.finale_requested or session.beat_index >= session.max_beats - 1:
+            speaker = self._choose_speaker(session)
+            return DirectorDecision(
+                next_speaker=speaker.name,
+                beat_type="finale",
+                instruction="Tie the scene together in one crisp curtain-call line.",
+                stage_effect="curtain_fall",
+                should_end_scene=True,
+                reason_summary="Finale requested or final beat reached; closing the scene cleanly.",
+            )
+
+        if session.latest_prop is not None:
+            speaker = self._choose_speaker(session)
+            return DirectorDecision(
+                next_speaker=speaker.name,
+                beat_type="evidence_or_prop",
+                instruction=f"Use the {session.latest_prop} as evidence and make it matter immediately.",
+                stage_effect="prop_table_glow",
+                uses_prop=True,
+                reason_summary=f"Latest audience prop {session.latest_prop} should affect the next beat.",
+            )
+
+        summoned_actor = self._unused_summoned_actor(session)
+        if summoned_actor is not None:
+            return DirectorDecision(
+                next_speaker=summoned_actor.name,
+                beat_type="chaos_or_intervention",
+                instruction="Enter the scene with one specific complication, then hand control back.",
+                stage_effect="entrance_sparkle",
+                reason_summary=f"Newly summoned actor {summoned_actor.name} has not spoken yet.",
+            )
+
+        beat_type = BEAT_ARC[min(session.beat_index, len(BEAT_ARC) - 1)]
+        speaker = self._choose_speaker(session)
+        reveal_secret = beat_type == "secret_reveal"
+        return DirectorDecision(
+            next_speaker=speaker.name,
+            beat_type=beat_type,
+            instruction=self._instruction_for_beat(beat_type, reveal_secret),
+            stage_effect=self._effect_for_beat(beat_type),
+            reveal_secret=reveal_secret,
+            should_end_scene=beat_type == "finale",
+            reason_summary=f"Following the compact six-beat arc with {beat_type}.",
+        )
+
+    def _choose_speaker(self, session: TheaterSession) -> Actor:
+        latest_speaker = session.transcript[-1].speaker if session.transcript else None
+        counts = Counter(beat.speaker for beat in session.transcript)
+        candidates = [actor for actor in session.actors if actor.name != latest_speaker] or session.actors
+        target_index = session.beat_index % len(session.actors)
+        indexed_actor = session.actors[target_index]
+        if indexed_actor in candidates and counts[indexed_actor.name] <= min(counts[actor.name] for actor in candidates):
+            return indexed_actor
+        return min(candidates, key=lambda actor: (counts[actor.name], session.actors.index(actor)))
+
+    def _unused_summoned_actor(self, session: TheaterSession) -> Actor | None:
+        spoken = {beat.speaker for beat in session.transcript}
+        for actor in session.actors[3:]:
+            if actor.name not in spoken:
+                return actor
+        return None
+
+    def _instruction_for_beat(self, beat_type: str, reveal_secret: bool) -> str:
+        if reveal_secret:
+            return "Reveal your secret directly, but keep it playful and stage-ready."
+        return {
+            "setup": "Establish the premise and your role in one clear line.",
+            "denial_or_contradiction": "Contradict the premise with theatrical confidence.",
+            "evidence_or_prop": "Present a clue or prop as if it changes the whole case.",
+            "chaos_or_intervention": "React to the audience and escalate the scene briefly.",
+            "finale": "End the scene with a clean button and a bow.",
+        }.get(beat_type, "Keep the scene moving with one short line.")
+
+    def _effect_for_beat(self, beat_type: str) -> str:
+        return {
+            "setup": "warm_spotlight",
+            "denial_or_contradiction": "quick_blackout",
+            "evidence_or_prop": "prop_table_glow",
+            "secret_reveal": "single_spotlight",
+            "chaos_or_intervention": "confetti_rustle",
+            "finale": "curtain_fall",
+        }[beat_type]
+
+
 def run_one_beat(session: TheaterSession | None) -> TheaterSession | None:
     if session is None:
         return None
@@ -21,12 +109,26 @@ def run_one_beat(session: TheaterSession | None) -> TheaterSession | None:
         session.trace_events.append("beat_skipped:curtain_already_fallen")
         return session
 
-    beat_type = "finale" if session.finale_requested else BEAT_ARC[session.beat_index]
-    speaker = session.actors[session.beat_index % len(session.actors)]
-    prop = session.latest_prop
+    decision = DirectorPolicy().decide(session)
+    speaker = _actor_by_name(session, decision.next_speaker)
+    prop = session.latest_prop if decision.uses_prop else None
     if prop is not None:
         speaker.held_prop = prop
-    backend_generation = generate_actor_response(session, beat_type, speaker, prop)
+
+    session.director_log.append(
+        "Director decision: "
+        f"{decision.beat_type} for {speaker.name}; {decision.reason_summary}"
+    )
+    session.trace_events.append(
+        "director_decision:"
+        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}"
+    )
+
+    backend_generation = generate_actor_response(session, decision, speaker, prop)
     session.beat_index += 1
 
     response = backend_generation.response
@@ -35,16 +137,18 @@ def run_one_beat(session: TheaterSession | None) -> TheaterSession | None:
         line=response.line,
         emotion=response.emotion,
         gesture=response.gesture,
-        stage_effect=response.stage_effect,
+        stage_effect=response.stage_effect or decision.stage_effect,
         tool_request=response.tool_request,
     )
     session.transcript.append(beat)
+
     if prop is not None:
         session.latest_prop = None
         session.director_log.append(f"{speaker.name} picked up {prop} and used it in the scene.")
-        session.trace_events.append(f"prop_handled:{prop}:{speaker.name}")
+        session.trace_events.append(f"prop_used:{prop}:{speaker.name}")
+
     session.director_log.append(
-        f"Beat {session.beat_index}/{session.max_beats}: {beat_type} assigned to {speaker.name}."
+        f"Beat {session.beat_index}/{session.max_beats}: {decision.beat_type} assigned to {speaker.name}."
     )
     session.director_log.append(
         "Backend "
@@ -56,7 +160,16 @@ def run_one_beat(session: TheaterSession | None) -> TheaterSession | None:
         session.director_log.append(f"Model id: {backend_generation.model_id}.")
     if backend_generation.error:
         session.director_log.append(f"Backend fallback reason: {backend_generation.error}.")
-    session.trace_events.append(f"beat_added:{session.beat_index}:{beat_type}")
+
+    session.trace_events.append(f"beat_added:{session.beat_index}:{decision.beat_type}")
+    session.trace_events.append(
+        "actor_response:"
+        f"speaker={speaker.name}:"
+        f"backend={backend_generation.backend_name}:"
+        f"validation={backend_generation.validation_status}"
+    )
+    if backend_generation.fallback_used:
+        session.trace_events.append(f"fallback_used:{backend_generation.backend_name}:{backend_generation.validation_status}")
     session.trace_events.append(
         "backend_result:"
         f"{backend_generation.backend_name}:"
@@ -67,10 +180,11 @@ def run_one_beat(session: TheaterSession | None) -> TheaterSession | None:
         f"latency_ms={backend_generation.latency_ms}"
     )
 
-    if beat_type == "finale":
+    if decision.should_end_scene or decision.beat_type == "finale":
         session.beat_index = session.max_beats
         session.finale_requested = True
         session.director_log.append("Finale reached; curtain falls cleanly.")
+        session.trace_events.append("finale_triggered")
         session.trace_events.append("scene_completed")
 
     return session
@@ -83,3 +197,10 @@ def run_full_act(session: TheaterSession | None) -> TheaterSession | None:
     while session.beat_index < session.max_beats:
         run_one_beat(session)
     return session
+
+
+def _actor_by_name(session: TheaterSession, actor_name: str) -> Actor:
+    for actor in session.actors:
+        if actor.name == actor_name:
+            return actor
+    return session.actors[session.beat_index % len(session.actors)]

puppet_theater/models.py

@@ -1,8 +1,20 @@
 from dataclasses import dataclass, field
 
+from typing import Literal
+
 from pydantic import BaseModel, Field, field_validator
 
 
+BeatType = Literal[
+    "setup",
+    "denial_or_contradiction",
+    "evidence_or_prop",
+    "secret_reveal",
+    "chaos_or_intervention",
+    "finale",
+]
+
+
 class ActorResponse(BaseModel):
     line: str = Field(description="Short, stage-ready puppet dialogue.")
     emotion: str
@@ -27,6 +39,25 @@ class ActorResponse(BaseModel):
         return cleaned or None
 
 
+class DirectorDecision(BaseModel):
+    next_speaker: str
+    beat_type: BeatType
+    instruction: str
+    stage_effect: str
+    uses_prop: bool = False
+    reveal_secret: bool = False
+    should_end_scene: bool = False
+    reason_summary: str
+
+    @field_validator("next_speaker", "instruction", "stage_effect", "reason_summary")
+    @classmethod
+    def require_text(cls, value: str) -> str:
+        cleaned = " ".join(value.strip().split())
+        if not cleaned:
+            raise ValueError("field must not be empty")
+        return cleaned
+
+
 @dataclass
 class Actor:
     name: str

puppet_theater/prompts.py

@@ -14,6 +14,9 @@ Beat type: {beat_type}
 Speaker: {speaker_name}
 Speaker goal: {speaker_goal}
 Speaker style: {speaker_style}
+Director instruction: {director_instruction}
+Reveal secret this beat: {reveal_secret}
+Suggested stage effect: {stage_effect}
 Audience action: {audience_action}
 Latest prop: {latest_prop}
 """