refactor: add model backend foundation

app.py

@@ -27,6 +27,7 @@ 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"
 PLAYBACK_DELAY_SECONDS = 0.75
 PROP_EMOJI = {
     "rubber duck": "🐤",
@@ -911,12 +912,23 @@ def render_trace(session: TheaterSession | None) -> str:
     return "\n".join(f"- {entry}" for entry in session.trace_events)
 
 
+def render_backend_settings(session: TheaterSession | None) -> str:
+    backend_name = session.backend_name if session is not None else "deterministic"
+    return (
+        f"Active backend: {backend_name}\n"
+        "Available backends: deterministic\n"
+        "LLM backends: not configured\n"
+        "Fallback behavior: invalid model output falls back to deterministic actor lines"
+    )
+
+
 def render_outputs(session: TheaterSession | None):
     return (
         render_stage(session),
         render_transcript(session),
         render_director_log(session),
         render_trace(session),
+        render_backend_settings(session),
     )
 
 
@@ -929,6 +941,7 @@ def create_show(premise: str, session: TheaterSession | None):
             "No premise yet. Add a premise to raise the curtain.",
             EMPTY_DIRECTOR_LOG,
             EMPTY_TRACE,
+            EMPTY_BACKEND,
         )
 
     session = create_show_from_premise(premise)
@@ -945,12 +958,13 @@ def reset_show():
         EMPTY_TRANSCRIPT,
         EMPTY_DIRECTOR_LOG,
         EMPTY_TRACE,
+        EMPTY_BACKEND,
     )
 
 
 def advance_one_beat(session: TheaterSession | None):
     if session is None:
-        return None, EMPTY_STAGE, "Create a show before running a beat.", EMPTY_DIRECTOR_LOG, EMPTY_TRACE
+        return None, EMPTY_STAGE, "Create a show before running a beat.", EMPTY_DIRECTOR_LOG, EMPTY_TRACE, EMPTY_BACKEND
 
     session = run_one_beat(session)
     return session, *render_outputs(session)
@@ -958,7 +972,7 @@ def advance_one_beat(session: TheaterSession | None):
 
 def advance_full_act(session: TheaterSession | None):
     if session is None:
-        yield None, EMPTY_STAGE, "Create a show before running the full act.", EMPTY_DIRECTOR_LOG, EMPTY_TRACE
+        yield None, EMPTY_STAGE, "Create a show before running the full act.", EMPTY_DIRECTOR_LOG, EMPTY_TRACE, EMPTY_BACKEND
         return
 
     if session.beat_index >= session.max_beats:
@@ -975,7 +989,7 @@ def advance_full_act(session: TheaterSession | None):
 
 def throw_audience_prop(session: TheaterSession | None, prop_name: str):
     if session is None:
-        return None, EMPTY_STAGE, "Create a show before throwing a prop.", EMPTY_DIRECTOR_LOG, EMPTY_TRACE
+        return None, EMPTY_STAGE, "Create a show before throwing a prop.", EMPTY_DIRECTOR_LOG, EMPTY_TRACE, EMPTY_BACKEND
 
     session = throw_prop(session, prop_name)
     return session, *render_outputs(session)
@@ -983,7 +997,7 @@ def throw_audience_prop(session: TheaterSession | None, prop_name: str):
 
 def summon_audience_actor(session: TheaterSession | None, actor_name: str):
     if session is None:
-        return None, EMPTY_STAGE, "Create a show before summoning an actor.", EMPTY_DIRECTOR_LOG, EMPTY_TRACE
+        return None, EMPTY_STAGE, "Create a show before summoning an actor.", EMPTY_DIRECTOR_LOG, EMPTY_TRACE, EMPTY_BACKEND
 
     session = summon_actor(session, actor_name)
     return session, *render_outputs(session)
@@ -991,7 +1005,7 @@ def summon_audience_actor(session: TheaterSession | None, actor_name: str):
 
 def request_audience_finale(session: TheaterSession | None):
     if session is None:
-        return None, EMPTY_STAGE, "Create a show before requesting a finale.", EMPTY_DIRECTOR_LOG, EMPTY_TRACE
+        return None, EMPTY_STAGE, "Create a show before requesting a finale.", EMPTY_DIRECTOR_LOG, EMPTY_TRACE, EMPTY_BACKEND
 
     session = request_finale(session)
     return session, *render_outputs(session)
@@ -1076,36 +1090,43 @@ with gr.Blocks(title="AI Puppet Theater") as app:
             lines=6,
             interactive=False,
         )
+    with gr.Accordion("Backend", open=False):
+        backend_output = gr.Textbox(
+            value=EMPTY_BACKEND,
+            label="Model Settings",
+            lines=4,
+            interactive=False,
+        )
 
     create_button.click(
         create_show,
         inputs=[premise_input, session_state],
-        outputs=[session_state, stage_output, transcript_output, director_output, trace_output],
+        outputs=[session_state, stage_output, transcript_output, director_output, trace_output, backend_output],
     )
     run_one_button.click(
         advance_one_beat,
         inputs=[session_state],
-        outputs=[session_state, stage_output, transcript_output, director_output, trace_output],
+        outputs=[session_state, stage_output, transcript_output, director_output, trace_output, backend_output],
     )
     run_full_button.click(
         advance_full_act,
         inputs=[session_state],
-        outputs=[session_state, stage_output, transcript_output, director_output, trace_output],
+        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],
-        outputs=[session_state, stage_output, transcript_output, director_output, trace_output],
+        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],
-        outputs=[session_state, stage_output, transcript_output, director_output, trace_output],
+        outputs=[session_state, stage_output, transcript_output, director_output, trace_output, backend_output],
     )
     request_finale_button.click(
         request_audience_finale,
         inputs=[session_state],
-        outputs=[session_state, stage_output, transcript_output, director_output, trace_output],
+        outputs=[session_state, stage_output, transcript_output, director_output, trace_output, backend_output],
     )
     reset_button.click(
         reset_show,
@@ -1118,6 +1139,7 @@ with gr.Blocks(title="AI Puppet Theater") as app:
             transcript_output,
             director_output,
             trace_output,
+            backend_output,
         ],
     )
 

puppet_theater/__init__.py

@@ -1,14 +1,20 @@
 from puppet_theater.actions import request_finale, summon_actor, throw_prop
+from puppet_theater.backends import DeterministicBackend, ModelBackend, generate_actor_response, parse_actor_output
 from puppet_theater.director import BEAT_ARC, run_full_act, run_one_beat
-from puppet_theater.models import Actor, Beat, TheaterSession
+from puppet_theater.models import Actor, ActorResponse, Beat, TheaterSession
 from puppet_theater.session import create_show_from_premise
 
 __all__ = [
     "Actor",
+    "ActorResponse",
     "BEAT_ARC",
     "Beat",
+    "DeterministicBackend",
+    "ModelBackend",
     "TheaterSession",
     "create_show_from_premise",
+    "generate_actor_response",
+    "parse_actor_output",
     "request_finale",
     "run_full_act",
     "run_one_beat",

puppet_theater/backends.py

@@ -0,0 +1,180 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+import json
+from typing import Any
+
+from pydantic import ValidationError
+
+from puppet_theater.models import Actor, ActorResponse, TheaterSession
+
+
+MAX_ACTOR_LINE_CHARS = 220
+
+
+@dataclass(frozen=True)
+class BackendGeneration:
+    response: ActorResponse
+    backend_name: str
+    fallback_used: bool
+    validation_status: str
+
+
+class ModelBackend(ABC):
+    name: str = "base"
+
+    @abstractmethod
+    def generate_actor_response(
+        self,
+        session: TheaterSession,
+        beat_type: str,
+        speaker: Actor,
+        prop: str | None,
+    ) -> ActorResponse | dict[str, Any] | str:
+        """Return raw or structured actor output for one beat."""
+
+
+class DeterministicBackend(ModelBackend):
+    name = "deterministic"
+
+    def generate_actor_response(
+        self,
+        session: TheaterSession,
+        beat_type: str,
+        speaker: Actor,
+        prop: str | None,
+    ) -> ActorResponse:
+        return deterministic_actor_response(session, beat_type, speaker, prop)
+
+
+def deterministic_actor_response(
+    session: TheaterSession,
+    beat_type: str,
+    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),
+        tool_request=None,
+    )
+
+
+def generate_actor_response(
+    session: TheaterSession,
+    beat_type: str,
+    speaker: Actor,
+    prop: str | None,
+    backend: ModelBackend | None = None,
+) -> BackendGeneration:
+    active_backend = backend or DeterministicBackend()
+    raw_output = active_backend.generate_actor_response(session, beat_type, speaker, prop)
+    response, validation_status = parse_actor_output(raw_output)
+    if response is not None:
+        return BackendGeneration(
+            response=response,
+            backend_name=active_backend.name,
+            fallback_used=False,
+            validation_status=validation_status,
+        )
+
+    fallback_response = deterministic_actor_response(session, beat_type, speaker, prop)
+    return BackendGeneration(
+        response=fallback_response,
+        backend_name=active_backend.name,
+        fallback_used=True,
+        validation_status=validation_status,
+    )
+
+
+def parse_actor_output(raw_output: ActorResponse | dict[str, Any] | str) -> tuple[ActorResponse | None, str]:
+    parsed = _coerce_actor_output(raw_output)
+    if parsed is None:
+        return None, "invalid_schema"
+
+    try:
+        response = ActorResponse.model_validate(parsed)
+    except ValidationError:
+        return None, "invalid_required_fields"
+
+    if not response.line.strip():
+        return None, "invalid_empty_line"
+
+    if len(response.line) > MAX_ACTOR_LINE_CHARS:
+        capped_line = response.line[: MAX_ACTOR_LINE_CHARS - 3].rstrip() + "..."
+        response = response.model_copy(update={"line": capped_line})
+        return response, "valid_line_capped"
+
+    return response, "valid"
+
+
+def _coerce_actor_output(raw_output: ActorResponse | dict[str, Any] | str) -> ActorResponse | dict[str, Any] | None:
+    if isinstance(raw_output, ActorResponse):
+        return raw_output
+    if isinstance(raw_output, dict):
+        return raw_output
+    if isinstance(raw_output, str):
+        text = raw_output.strip()
+        if not text:
+            return None
+        try:
+            decoded = json.loads(text)
+        except json.JSONDecodeError:
+            return None
+        return decoded if isinstance(decoded, dict) else None
+    return None
+
+
+def _line_for_beat(
+    session: TheaterSession,
+    beat_type: str,
+    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."
+    if beat_type == "setup":
+        return f"I see it clearly: {session.premise}, and somehow I am in charge."
+    if beat_type == "denial_or_contradiction":
+        return "Absolutely not. The premise is innocent, which is exactly what makes it suspicious."
+    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 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."
+
+
+def _emotion_for_beat(beat_type: str) -> str:
+    return {
+        "setup": "curious",
+        "denial_or_contradiction": "defensive",
+        "evidence_or_prop": "suspicious",
+        "secret_reveal": "confessional",
+        "chaos_or_intervention": "frantic",
+        "finale": "triumphant",
+    }[beat_type]
+
+
+def _gesture_for_beat(beat_type: str) -> str:
+    return {
+        "setup": "raise_curtain",
+        "denial_or_contradiction": "shake_head",
+        "evidence_or_prop": "present_prop",
+        "secret_reveal": "lean_to_audience",
+        "chaos_or_intervention": "flail_politely",
+        "finale": "deep_bow",
+    }[beat_type]
+
+
+def _effect_for_beat(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]

puppet_theater/director.py

@@ -1,3 +1,4 @@
+from puppet_theater.backends import generate_actor_response
 from puppet_theater.models import Beat, TheaterSession
 
 
@@ -11,28 +12,6 @@ BEAT_ARC = [
 ]
 
 
-def _line_for_beat(
-    session: TheaterSession,
-    beat_type: str,
-    speaker_name: str,
-    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."
-    if beat_type == "setup":
-        return f"I see it clearly: {session.premise}, and somehow I am in charge."
-    if beat_type == "denial_or_contradiction":
-        return "Absolutely not. The premise is innocent, which is exactly what makes it suspicious."
-    if beat_type == "evidence_or_prop":
-        return "I found a prop with fingerprints, glitter, and a very dramatic attitude."
-    if beat_type == "secret_reveal":
-        actor = next(actor for actor in session.actors if actor.name == speaker_name)
-        return f"I confess: {actor.secret}"
-    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."
-
-
 def run_one_beat(session: TheaterSession | None) -> TheaterSession | None:
     if session is None:
         return None
@@ -47,16 +26,17 @@ def run_one_beat(session: TheaterSession | None) -> TheaterSession | None:
     prop = session.latest_prop
     if prop is not None:
         speaker.held_prop = prop
-    line = _line_for_beat(session, beat_type, speaker.name, prop)
+    backend_generation = generate_actor_response(session, beat_type, speaker, prop)
     session.beat_index += 1
 
+    response = backend_generation.response
     beat = Beat(
         speaker=speaker.name,
-        line=line,
-        emotion=_emotion_for_beat(beat_type),
-        gesture=_gesture_for_beat(beat_type),
-        stage_effect=_effect_for_beat(beat_type),
-        tool_request=None,
+        line=response.line,
+        emotion=response.emotion,
+        gesture=response.gesture,
+        stage_effect=response.stage_effect,
+        tool_request=response.tool_request,
     )
     session.transcript.append(beat)
     if prop is not None:
@@ -66,7 +46,18 @@ def run_one_beat(session: TheaterSession | None) -> TheaterSession | None:
     session.director_log.append(
         f"Beat {session.beat_index}/{session.max_beats}: {beat_type} assigned to {speaker.name}."
     )
+    session.director_log.append(
+        "Backend "
+        f"{backend_generation.backend_name} returned actor output "
+        f"({backend_generation.validation_status}, fallback={backend_generation.fallback_used})."
+    )
     session.trace_events.append(f"beat_added:{session.beat_index}:{beat_type}")
+    session.trace_events.append(
+        "backend_result:"
+        f"{backend_generation.backend_name}:"
+        f"fallback={backend_generation.fallback_used}:"
+        f"validation={backend_generation.validation_status}"
+    )
 
     if beat_type == "finale":
         session.beat_index = session.max_beats
@@ -84,36 +75,3 @@ def run_full_act(session: TheaterSession | None) -> TheaterSession | None:
     while session.beat_index < session.max_beats:
         run_one_beat(session)
     return session
-
-
-def _emotion_for_beat(beat_type: str) -> str:
-    return {
-        "setup": "curious",
-        "denial_or_contradiction": "defensive",
-        "evidence_or_prop": "suspicious",
-        "secret_reveal": "confessional",
-        "chaos_or_intervention": "frantic",
-        "finale": "triumphant",
-    }[beat_type]
-
-
-def _gesture_for_beat(beat_type: str) -> str:
-    return {
-        "setup": "raise_curtain",
-        "denial_or_contradiction": "shake_head",
-        "evidence_or_prop": "present_prop",
-        "secret_reveal": "lean_to_audience",
-        "chaos_or_intervention": "flail_politely",
-        "finale": "deep_bow",
-    }[beat_type]
-
-
-def _effect_for_beat(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]

puppet_theater/models.py

@@ -1,5 +1,31 @@
 from dataclasses import dataclass, field
 
+from pydantic import BaseModel, Field, field_validator
+
+
+class ActorResponse(BaseModel):
+    line: str = Field(description="Short, stage-ready puppet dialogue.")
+    emotion: str
+    gesture: str
+    stage_effect: str
+    tool_request: str | None = None
+
+    @field_validator("line", "emotion", "gesture", "stage_effect")
+    @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
+
+    @field_validator("tool_request")
+    @classmethod
+    def clean_optional_text(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        cleaned = " ".join(value.strip().split())
+        return cleaned or None
+
 
 @dataclass
 class Actor:
@@ -37,3 +63,4 @@ class TheaterSession:
     director_log: list[str] = field(default_factory=list)
     trace_events: list[str] = field(default_factory=list)
     finale_requested: bool = False
+    backend_name: str = "deterministic"

puppet_theater/prompts.py

@@ -0,0 +1,57 @@
+ACTOR_LINE_PROMPT = """You are writing one short puppet line for AI Puppet Theater.
+
+Return only JSON with these fields:
+- line: a short, stage-ready spoken line
+- emotion: one concise emotion label
+- gesture: one concise stage gesture label
+- stage_effect: one concise stage effect label
+- tool_request: null or one concise theatrical tool request
+
+Show title: {show_title}
+Premise: {premise}
+Setting: {setting}
+Beat type: {beat_type}
+Speaker: {speaker_name}
+Speaker goal: {speaker_goal}
+Speaker style: {speaker_style}
+Audience action: {audience_action}
+Latest prop: {latest_prop}
+"""
+
+
+DIRECTOR_DECISION_PROMPT = """You are the Director for AI Puppet Theater.
+
+Choose the next beat for a short puppet scene. Keep the scene tight, rotate speakers,
+respect finale requests, and avoid exposing actor secrets unless the beat calls for it.
+
+Return only JSON with these fields:
+- beat_type
+- speaker_name
+- reason_summary
+- should_end
+
+Show title: {show_title}
+Premise: {premise}
+Current beat: {beat_index}
+Maximum beats: {max_beats}
+Available actors: {actor_names}
+Recent transcript: {recent_transcript}
+Audience action: {audience_action}
+Finale requested: {finale_requested}
+"""
+
+
+CASTING_PROMPT = """You are casting a tiny improv puppet show.
+
+Create a small ensemble of puppet actors that can perform the premise quickly.
+Return only JSON with an actors array. Each actor must include:
+- name
+- avatar
+- goal
+- secret
+- speaking_style
+- tools
+
+Premise: {premise}
+Preferred actor count: {actor_count}
+"""

puppet_theater/session.py

@@ -61,6 +61,7 @@ def create_show_from_premise(premise: str) -> TheaterSession:
 
     director_log = [
         "Director created a deterministic six-beat show plan.",
+        "Active backend: deterministic.",
         f"Setting selected: {setting}.",
         "Three puppet actors are waiting for the first beat.",
     ]
@@ -68,6 +69,7 @@ def create_show_from_premise(premise: str) -> TheaterSession:
         "show_created",
         "actors_created:3",
         "director_plan_created",
+        "backend_active:deterministic",
     ]
 
     return TheaterSession(
@@ -84,4 +86,5 @@ def create_show_from_premise(premise: str) -> TheaterSession:
         director_log=director_log,
         trace_events=trace_events,
         finale_requested=False,
+        backend_name="deterministic",
     )