feat: add puppet theater session models

.python-version

@@ -0,0 +1 @@
+3.11

app.py

@@ -2,6 +2,8 @@ from html import escape
 
 import gradio as gr
 
+from puppet_theater import TheaterSession, create_show_from_premise
+
 
 EMPTY_STAGE = """
 <div class="stage-placeholder">
@@ -29,50 +31,128 @@ CUSTOM_CSS = """
 }
 .stage-live {
     background: linear-gradient(180deg, #1f2937 0%, #7c2d12 100%);
+    align-items: stretch;
+    text-align: left;
 }
 .stage-lights {
     font-size: 1.8rem;
     font-weight: 700;
+    text-align: center;
 }
 .stage-floor {
     max-width: 48rem;
     font-size: 1rem;
     line-height: 1.5;
+    margin: 0 auto;
+    text-align: center;
+}
+.actor-row {
+    display: grid;
+    grid-template-columns: repeat(3, minmax(0, 1fr));
+    gap: 0.75rem;
+    margin-top: 1rem;
+}
+.actor-card {
+    border: 1px solid rgba(255, 255, 255, 0.28);
+    border-radius: 8px;
+    background: rgba(255, 255, 255, 0.1);
+    padding: 0.85rem;
+}
+.actor-avatar {
+    font-size: 1.8rem;
+}
+.actor-name {
+    font-weight: 700;
+    margin-top: 0.25rem;
+}
+.actor-detail {
+    font-size: 0.9rem;
+    line-height: 1.35;
+    opacity: 0.92;
+    margin-top: 0.35rem;
+}
+.beat-counter {
+    margin-top: 1rem;
+    text-align: center;
+    font-weight: 700;
 }
 """
 
 
-def create_show(premise: str, session: dict | None):
+def render_stage(session: TheaterSession | None) -> str:
+    if session is None:
+        return EMPTY_STAGE
+
+    actor_cards = []
+    for actor in session.actors:
+        tools = ", ".join(actor.tools) if actor.tools else "none"
+        actor_cards.append(
+            f"""
+            <div class="actor-card">
+              <div class="actor-avatar">{escape(actor.avatar)}</div>
+              <div class="actor-name">{escape(actor.name)}</div>
+              <div class="actor-detail"><strong>Goal:</strong> {escape(actor.goal)}</div>
+              <div class="actor-detail"><strong>Style:</strong> {escape(actor.speaking_style)}</div>
+              <div class="actor-detail"><strong>Tools:</strong> {escape(tools)}</div>
+            </div>
+            """
+        )
+
+    return f"""
+    <div class="stage-placeholder stage-live">
+      <div class="stage-lights">{escape(session.show_title)}</div>
+      <div class="stage-floor">
+        <strong>Setting:</strong> {escape(session.setting)}<br />
+        <strong>Premise:</strong> {escape(session.premise)}
+      </div>
+      <div class="actor-row">
+        {''.join(actor_cards)}
+      </div>
+      <div class="beat-counter">Beat {session.beat_index} of {session.max_beats}</div>
+    </div>
+    """
+
+
+def render_notes(session: TheaterSession | None) -> str:
+    if session is None:
+        return EMPTY_TRANSCRIPT
+
+    transcript_lines = [
+        "Transcript:",
+        "No puppet lines yet. The first beat will be added in the next milestone.",
+    ]
+    if session.transcript:
+        transcript_lines = ["Transcript:"]
+        for beat in session.transcript:
+            transcript_lines.append(f"{beat.speaker}: {beat.line}")
+
+    director_lines = ["", "Director Log:"]
+    director_lines.extend(f"- {entry}" for entry in session.director_log)
+    director_lines.extend(["", "Trace Events:"])
+    director_lines.extend(f"- {entry}" for entry in session.trace_events)
+
+    return "\n".join(transcript_lines + director_lines)
+
+
+def create_show(premise: str, session: TheaterSession | None):
     premise = premise.strip()
     if not premise:
-        session = {"premise": "", "created": False}
         return (
-            session,
+            None,
             EMPTY_STAGE,
             "No premise yet. Add a premise to raise the curtain.",
         )
 
-    session = {"premise": premise, "created": True}
-    safe_premise = escape(premise)
-    stage = f"""
-    <div class="stage-placeholder stage-live">
-      <div class="stage-lights">Curtain Up</div>
-      <div class="stage-floor">Premise: {safe_premise}</div>
-    </div>
-    """
-    transcript = (
-        "Director: The puppet cast is waiting in the wings.\n\n"
-        "Stage Manager: This shell is ready for the deterministic skit engine."
-    )
-    return session, stage, transcript
+    session = create_show_from_premise(premise)
+    return session, render_stage(session), render_notes(session)
 
 
 def reset_show():
-    return {"premise": "", "created": False}, "", EMPTY_STAGE, EMPTY_TRANSCRIPT
+    return None, "", EMPTY_STAGE, EMPTY_TRANSCRIPT
 
 
-with gr.Blocks(title="AI Puppet Theater") as demo:
-    session_state = gr.State({"premise": "", "created": False})
+with gr.Blocks(title="AI Puppet Theater") as app:
+    session_state = gr.State(None)
 
     gr.Markdown(
         """
@@ -115,4 +195,4 @@ with gr.Blocks(title="AI Puppet Theater") as demo:
 
 
 if __name__ == "__main__":
-    demo.launch(css=CUSTOM_CSS)
+    app.launch(css=CUSTOM_CSS)

puppet_theater/__init__.py

@@ -0,0 +1,9 @@
+from puppet_theater.models import Actor, Beat, TheaterSession
+from puppet_theater.session import create_show_from_premise
+
+__all__ = [
+    "Actor",
+    "Beat",
+    "TheaterSession",
+    "create_show_from_premise",
+]

puppet_theater/models.py

@@ -0,0 +1,36 @@
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Actor:
+    name: str
+    avatar: str
+    goal: str
+    secret: str
+    speaking_style: str
+    tools: list[str] = field(default_factory=list)
+
+
+@dataclass
+class Beat:
+    speaker: str
+    line: str
+    emotion: str
+    gesture: str
+    stage_effect: str
+    tool_request: str | None = None
+
+
+@dataclass
+class TheaterSession:
+    show_title: str
+    premise: str
+    setting: str
+    actors: list[Actor]
+    beat_index: int = 0
+    max_beats: int = 6
+    transcript: list[Beat] = field(default_factory=list)
+    props: list[str] = field(default_factory=list)
+    director_log: list[str] = field(default_factory=list)
+    trace_events: list[str] = field(default_factory=list)
+    finale_requested: bool = False

puppet_theater/session.py

@@ -0,0 +1,85 @@
+from puppet_theater.models import Actor, TheaterSession
+
+
+def _clean_premise(premise: str) -> str:
+    cleaned = " ".join(premise.strip().split())
+    return cleaned or "A mysterious puppet show with no premise"
+
+
+def _title_from_premise(premise: str) -> str:
+    words = [word.strip(".,!?;:()[]{}\"'") for word in premise.split()]
+    keywords = [word.title() for word in words if len(word.strip(".,!?;:()[]{}\"'")) > 3]
+    if not keywords:
+        return "The Tiny Improv"
+    return f"The {' '.join(keywords[:4])}"
+
+
+def _setting_from_premise(premise: str) -> str:
+    lowered = premise.lower()
+    if "moon" in lowered or "space" in lowered or "star" in lowered:
+        return "a cardboard moon base with glittery stars and a squeaky hatch"
+    if "castle" in lowered or "dragon" in lowered or "wizard" in lowered:
+        return "a shoebox castle with velvet curtains and a suspicious tower"
+    if "detective" in lowered or "mystery" in lowered:
+        return "a rainy cardboard alley lit by one dramatic desk lamp"
+    if "kitchen" in lowered or "toaster" in lowered or "chef" in lowered:
+        return "a tiny kitchen counter where every appliance has stage fright"
+    return "a pocket-sized improv stage with painted flats and a wobbly spotlight"
+
+
+def create_show_from_premise(premise: str) -> TheaterSession:
+    cleaned_premise = _clean_premise(premise)
+    show_title = _title_from_premise(cleaned_premise)
+    setting = _setting_from_premise(cleaned_premise)
+
+    actors = [
+        Actor(
+            name="Pip the Director",
+            avatar="🎬",
+            goal="Keep the scene moving toward a crisp finale.",
+            secret="Has already misplaced the final cue card.",
+            speaking_style="brisk, theatrical, and slightly overconfident",
+            tools=["spotlight", "cue_cards"],
+        ),
+        Actor(
+            name="Mina Moonbutton",
+            avatar="🌙",
+            goal="Find the emotional truth hiding inside the premise.",
+            secret="Believes every prop is personally judging her.",
+            speaking_style="earnest, poetic, and prone to dramatic pauses",
+            tools=["monologue", "soft_lights"],
+        ),
+        Actor(
+            name="Bolt McJiggle",
+            avatar="🧰",
+            goal="Turn every problem into a practical stage gag.",
+            secret="Is secretly building a confetti finale backstage.",
+            speaking_style="punchy, practical, and full of suspicious confidence",
+            tools=["props", "sound_effects"],
+        ),
+    ]
+
+    director_log = [
+        "Director created a deterministic six-beat show plan.",
+        f"Setting selected: {setting}.",
+        "Three puppet actors are waiting for the first beat.",
+    ]
+    trace_events = [
+        "show_created",
+        "actors_created:3",
+        "director_plan_created",
+    ]
+
+    return TheaterSession(
+        show_title=show_title,
+        premise=cleaned_premise,
+        setting=setting,
+        actors=actors,
+        beat_index=0,
+        max_beats=6,
+        transcript=[],
+        props=[],
+        director_log=director_log,
+        trace_events=trace_events,
+        finale_requested=False,
+    )