fetch-initial-data-from-llm

.gitignore

@@ -1,6 +1,11 @@
 .venv/
 .uv-cache/
 
+# Local secrets (HF_TOKEN, etc.); never commit
+.env
+.env.*
+!.env.example
+
 __pycache__/
 *.py[cod]
 

README.md

@@ -29,6 +29,7 @@ AI Puppet Theater is a Hugging Face Gradio Space for the Build Small Hackathon,
 - [Model and Runtime](#model-and-runtime)
 - [Hackathon Targets](#hackathon-targets)
 - [Team](#team)
+- [Learning path (for contributors)](#learning-path-for-contributors)
 - [Local Development](#local-development)
 - [Configuration](#configuration)
 - [Actor Model Backends](#actor-model-backends)
@@ -36,6 +37,10 @@ AI Puppet Theater is a Hugging Face Gradio Space for the Build Small Hackathon,
 - [Fine-Tuning Artifacts](#fine-tuning-artifacts)
 - [Roadmap](#roadmap)
 
+## Learning path (for contributors)
+
+If you are new to Python or LLMs and want to understand how the Gradio UI connects to the Director / actor loop, read **[docs/LEARNING_PATH.md](docs/LEARNING_PATH.md)**. It mirrors the recommended reading order for this repository and includes a UI-to-engine handler map.
+
 ## Live Demo
 
 - **Hugging Face Space:** [AI Puppet Theater](https://huggingface.co/spaces/build-small-hackathon/AI-Puppet-Theater)
@@ -256,10 +261,18 @@ HF_API_MODEL_ID=Qwen/Qwen3-4B-Instruct-2507:nscale
 
 The default model string includes the provider suffix used by Hugging Face Inference Providers. If that model is unavailable through your selected provider, use another chat-compatible model id from Hugging Face Inference Providers.
 
+Premise casting (title, setting, minimal **backdrop_description**, director + puppets JSON) requests up to **`HF_API_SHOW_BIBLE_MAX_TOKENS`** completion tokens (default **1024**, clamped between 256 and 4096). When **`HF_SETTING_BACKDROP_IMAGE`** is not disabled (default on) and **`HF_TOKEN`** is set, the app generates a **JPEG backdrop from the `setting` sentence** via Hugging Face **text-to-image** (model **`HF_BACKDROP_T2I_MODEL`**, default `black-forest-labs/FLUX.1-schnell`; timeout **`HF_BACKDROP_T2I_TIMEOUT`**, default 90s). If that is off or fails after an LLM cast, a follow-up **chat** completion can still pick a stock **`backdrop_image_url`** (up to **`HF_API_BACKDROP_URL_MAX_TOKENS`**, default **256**). If that JSON was truncated at 200 tokens before, the UI fell back to the default Pip/Mina/Bolt cast; raising this cap fixes incomplete responses.
+
 Configure the token as a Hugging Face Space secret named `HF_TOKEN`. `HUGGINGFACEHUB_API_TOKEN` is also supported. Do not commit tokens to the repository, README, app code, logs, or trace output.
 
+For **local** runs, put `HF_TOKEN=...` in a file named `.env` at the **repository root** (next to `app.py`). The app loads that file on startup; you do not need to `export` it manually. A template is in [`.env.example`](.env.example).
+
 Local deterministic mode and app launch work without `HF_TOKEN`.
 
+### Stage backdrop
+
+The show’s **`setting`** string (for example *“A sun-dappled forest clearing with soft grass and distant trees, warm and quiet.”*) is the narrative stage description. When **`HF_TOKEN`** is configured and **`HF_SETTING_BACKDROP_IMAGE`** is not set to `0`/`false`/`off`, the app builds a **text-to-image** prompt from that setting (wide 16:9 puppet-stage framing, calm center, no text/watermarks) and calls the Hugging Face Inference API. The returned image is stored as an **inline JPEG data URL** on the session and used as the CSS stage background. If generation is disabled, fails, or there is no token, the app falls back to an LLM-picked stock **https** URL from **`backdrop_description`**, then to **keyword-matched stock images** in `puppet_theater/session.py` (`_BACKDROP_RULES`). Set **`HF_SETTING_BACKDROP_IMAGE=0`** to skip image generation and use URL/keyword flow only.
+
 ### Voice modes
 
 Voice is optional. **Off** remains the default and the app works without audio support.

app.py

@@ -8,6 +8,12 @@ import tempfile
 import time
 from time import sleep
 
+from dotenv import load_dotenv
+
+# Repo-root .env (HF_TOKEN, etc.). Must run before importing puppet_theater so
+# load_dotenv is not cwd-dependent (IDEs / `gradio` may use a different cwd).
+load_dotenv(Path(__file__).resolve().parent / ".env")
+
 os.environ["GRADIO_SSR_MODE"] = "False"
 
 import gradio as gr
@@ -1145,10 +1151,21 @@ body,
     display: inline-grid;
     font-size: 1.7rem;
     height: 3rem;
+    overflow: hidden;
     place-items: center;
     text-align: center;
     width: 3rem;
 }
+.actor-avatar.has-image {
+    padding: 0;
+}
+.actor-avatar .actor-avatar-img {
+    border-radius: 999px;
+    display: block;
+    height: 100%;
+    object-fit: cover;
+    width: 100%;
+}
 .actor-name {
     color: #f8efe4;
     font-weight: 700;
@@ -1409,6 +1426,13 @@ body,
     line-height: 1.2;
     margin-bottom: 0.28rem;
 }
+.agent-state-avatar {
+    border-radius: 4px;
+    height: 1.15rem;
+    object-fit: cover;
+    vertical-align: text-bottom;
+    width: 1.15rem;
+}
 .agent-state-line {
     color: #f8efe4;
     font-size: 0.78rem;
@@ -1654,6 +1678,7 @@ body,
 .actor-avatar {
     font-size: 2rem;
     height: 3.3rem;
+    overflow: hidden;
     width: 3.3rem;
 }
 .actor-name {
@@ -1799,6 +1824,7 @@ body,
 .actor-avatar {
     font-size: 1.65rem;
     height: 2.55rem;
+    overflow: hidden;
     width: 2.55rem;
 }
 .actor-name {
@@ -2350,12 +2376,17 @@ def render_stage(session: TheaterSession | None) -> str:
               <div class="speech-line">{escape(latest_beat.line)}</div>
             </div>
             """
+        avatar_class = "actor-avatar has-image" if actor.avatar_image_url else "actor-avatar"
+        if actor.avatar_image_url:
+            avatar_inner = f'<img class="actor-avatar-img" src="{escape(actor.avatar_image_url)}" alt="" loading="lazy" />'
+        else:
+            avatar_inner = escape(actor.avatar)
         actor_columns.append(
             f"""
             <div class="actor-column">
               {bubble_html}
               <div class="actor-card{active_class}">
-                <div class="actor-avatar">{escape(actor.avatar)}</div>
+                <div class="{avatar_class}">{avatar_inner}</div>
                 <div class="actor-name">{escape(actor.name)}</div>
                 {active_label}
                 <div class="actor-detail">{escape(role_line)}</div>
@@ -2402,10 +2433,18 @@ def render_stage(session: TheaterSession | None) -> str:
         </div>
         """
 
+    backdrop_style = ""
+    if session.backdrop_image_url:
+        u = escape(session.backdrop_image_url)
+        backdrop_style = (
+            f' style="background-image: linear-gradient(180deg, rgba(42,20,38,0.82) 0%, rgba(19,9,17,0.88) 62%, rgba(13,6,14,0.92) 100%), url({u}); '
+            'background-size: cover; background-position: center; background-blend-mode: multiply;"'
+        )
+
     return f"""
     <div class="puppet-stage stage-live">
       <div class="stage-valance"></div>
-      <div class="stage-backdrop">
+      <div class="stage-backdrop"{backdrop_style}>
         {curtain_html}
         <div class="stage-marquee">{escape(session.show_title)}</div>
         <div class="stage-copy">
@@ -2465,10 +2504,15 @@ def render_agent_state(session: TheaterSession | None) -> str:
         held = ", ".join(held_props) if held_props else "none"
         recent_memory = actor.recent_memory[-1] if actor.recent_memory else "No memory yet."
         current_goal = actor.current_goal or actor.goal
+        face = (
+            f'<img class="agent-state-avatar" src="{escape(actor.avatar_image_url)}" alt="" /> '
+            if actor.avatar_image_url
+            else f"{escape(actor.avatar)} "
+        )
         cards.append(
             f"""
             <div class="agent-state-card">
-              <div class="agent-state-name">{escape(actor.avatar)} {escape(actor.name)}</div>
+              <div class="agent-state-name">{face}{escape(actor.name)}</div>
               <div class="agent-state-line"><strong>Mood:</strong> {escape(actor.mood)}</div>
               <div class="agent-state-line"><strong>Goal:</strong> {escape(current_goal)}</div>
               <div class="agent-state-line"><strong>Props:</strong> {escape(held)}</div>

docs/LEARNING_PATH.md

@@ -0,0 +1,213 @@
+# Learning path: AI Puppet Theater
+
+This guide walks a new contributor from Python and LLM basics through this repository so you can **trace one user action end-to-end** and **change the engine or UI safely**.
+
+Companion docs: [AGENTS.md](../AGENTS.md) (agent and product rules), [README.md](../README.md) (features and architecture images under `assets/`).
+
+---
+
+## Phase 0: Environment and vocabulary
+
+### Run the app
+
+```bash
+uv sync
+uv run python app.py
+# or, for reload while editing:
+uv run gradio app.py
+```
+
+Open `http://127.0.0.1:7860`. Create a show, use **Run One Beat**, throw a prop, open **Behind the Curtain**. You will see the same concepts the code names: session, beats, director log, trace.
+
+### Python building blocks used here
+
+- **Modules and imports** — `app.py` imports a small public API from `puppet_theater` (see [`puppet_theater/__init__.py`](../puppet_theater/__init__.py)).
+- **`dataclasses`** — mutable “world state”: [`Actor`](../puppet_theater/models.py), [`Beat`](../puppet_theater/models.py), [`TheaterSession`](../puppet_theater/models.py).
+- **Pydantic `BaseModel`** — validated “messages” often produced from LLM text: [`DirectorDecision`](../puppet_theater/models.py), [`ActorResponse`](../puppet_theater/models.py), [`ToolRequest`](../puppet_theater/models.py).
+- **Type hints** — e.g. `str | None`, `list[Beat]`.
+- **In-place session updates** — most functions take `TheaterSession`, mutate it, and return the same object (not a copy).
+
+### LLM vocabulary in this project
+
+- **Prompt** — text sent to a model; see [`puppet_theater/prompts.py`](../puppet_theater/prompts.py).
+- **Structured output** — the app expects JSON-shaped answers, parses them, and validates with Pydantic. Bad JSON or timeouts → **fallback** to deterministic templates so the Space always runs.
+
+---
+
+## Phase 1: The nouns of the show (`models.py`)
+
+Read [`puppet_theater/models.py`](../puppet_theater/models.py) end-to-end.
+
+### TheaterSession vs Beat
+
+| | **`TheaterSession`** | **`Beat`** |
+|---|----------------------|------------|
+| **Role** | The entire live show: cast, configuration, pacing budget, transcript history, logs, trace. | One row of dialogue / stage moment in the transcript. |
+| **Mutability** | Updated every audience action and every beat (beat counter, actors’ mood, etc.). | Created once per beat and appended to `session.transcript`; treat as immutable after append. |
+| **Contains** | `actors`, `beat_index`, `min_beats` / `target_beats` / `max_beats`, `transcript`, `latest_prop`, `director_log`, `trace_events`, `backend_name`, `director_mode`, … | `speaker`, `intent`, `line`, `emotion`, `gesture`, `stage_effect`, optional `memory_update` and `tool_request`. |
+
+**Checkpoint:** Explain aloud: “The session is the notebook; each beat is one line the puppets spoke.”
+
+### Pydantic vs dataclass in this file
+
+- **Pydantic** — strict validation for fields that might come from model JSON (length limits, non-empty strings).
+- **Dataclass** — convenient structured bags for runtime state the code controls directly.
+
+Public exports are listed in [`puppet_theater/__init__.py`](../puppet_theater/__init__.py).
+
+---
+
+## Phase 2: Creating a show and audience actions
+
+1. **[`puppet_theater/session.py`](../puppet_theater/session.py)** — [`create_show_from_premise`](../puppet_theater/session.py) builds `show_title`, `setting`, the default three [`Actor`](../puppet_theater/models.py) instances, beat budget from [`resolve_show_length`](../puppet_theater/session.py), copies backend/director/temperature settings onto the session, seeds `director_log`, and records trace events (`show_created`, `actors_created`, `director_plan_created`).
+
+2. **[`puppet_theater/actions.py`](../puppet_theater/actions.py)** — Audience mutators:
+   - [`throw_prop`](../puppet_theater/actions.py) — appends to `session.props`, sets `latest_prop`, updates `latest_audience_action` and `director_log`, traces `audience_action`.
+   - [`summon_actor`](../puppet_theater/actions.py) — appends a new `Actor` (cap `MAX_ACTORS`), or logs a skip if full.
+   - [`request_finale`](../puppet_theater/actions.py) — sets `finale_requested` so the Director policy can force a finale.
+
+**Checkpoint:** Trace “throw rubber duck” from UI → `throw_prop` → `session.latest_prop` → next Director beat may set `uses_prop=True` (see deterministic policy when `latest_prop` is set in [`DirectorPolicy.decide`](../puppet_theater/director.py)).
+
+---
+
+## Phase 3: One beat — the main pipeline (`director.py`)
+
+Read [`puppet_theater/director.py`](../puppet_theater/director.py) with focus on:
+
+- [`story_progress`](../puppet_theater/director.py) / [`story_phase`](../puppet_theater/director.py) — pacing helpers from `beat_index` and `target_beats`.
+- [`choose_director_decision`](../puppet_theater/director.py) — branches on `session.director_mode`: `hf_api` → `HFAPIDirectorPolicy`, `openbmb` → `OpenBMBDirectorPolicy`, else [`DirectorPolicy`](../puppet_theater/director.py) (deterministic).
+- [`run_one_beat`](../puppet_theater/director.py) — orchestrates one turn:
+  1. Skip if `beat_index >= max_beats`.
+  2. Call `choose_director_decision` → [`DirectorDecision`](../puppet_theater/models.py).
+  3. Resolve speaker; optionally attach `latest_prop` if decision uses prop.
+  4. Append director log lines and `add_trace_event(..., "director_decision", ...)`.
+  5. [`generate_actor_response`](../puppet_theater/backends.py) (from `backends`) → [`ActorResponse`](../puppet_theater/models.py).
+  6. Increment `beat_index`, build [`Beat`](../puppet_theater/models.py), append to `transcript`.
+  7. [`apply_actor_state_update`](../puppet_theater/director.py) — mood, memory, secret status, held props.
+  8. [`run_actor_tool_request`](../puppet_theater/tools.py) — optional tool side effects; may adjust `beat.stage_effect`.
+  9. Clear `latest_prop` if consumed; more logs and trace (`beat_added`, `actor_response`, …).
+  10. If finale: clamp `beat_index` to `max_beats`, set `finale_requested`, trace `scene_completed`.
+
+- [`run_full_act`](../puppet_theater/director.py) — `while session.beat_index < session.max_beats: run_one_beat(session)`.
+
+```mermaid
+flowchart LR
+  subgraph beat [run_one_beat]
+    D[choose_director_decision]
+    A[generate_actor_response]
+    T[append Beat to transcript]
+    S[apply_actor_state_update]
+    U[run_actor_tool_request]
+  end
+  Session[TheaterSession]
+  Session --> D
+  D --> A
+  A --> T
+  T --> S
+  S --> U
+  U --> Session
+```
+
+**Checkpoint:** Without opening `app.py`, narrate one beat from Director decision through transcript line.
+
+---
+
+## Phase 4: Backends — where the LLM lives (`backends.py`)
+
+Read [`puppet_theater/backends.py`](../puppet_theater/backends.py) with this map:
+
+- **`ModelBackend`** — abstract [`generate_actor_response`](../puppet_theater/backends.py) per backend.
+- **Implementations** — [`DeterministicBackend`](../puppet_theater/backends.py) (always works), [`OpenBMBTransformersBackend`](../puppet_theater/backends.py) (local Transformers; ZeroGPU hooks in [`puppet_theater/zerogpu.py`](../puppet_theater/zerogpu.py)), [`HFAPIBackend`](../puppet_theater/backends.py) (hosted inference).
+- **[`generate_actor_response`](../puppet_theater/backends.py)** (module-level) — picks backend from `session.backend_name`, runs generation, [`parse_actor_output`](../puppet_theater/backends.py), optional repair, then deterministic fallback on failure (mirrors Director policies’ try/validate/fallback pattern).
+
+**Checkpoint:** Why does the demo run without an HF token? Because `backend_name` and `director_mode` default to `deterministic`, which never calls the network.
+
+Optional deep read: [`puppet_theater/prompts.py`](../puppet_theater/prompts.py).
+
+---
+
+## Phase 5: Tools and trace
+
+### Tools ([`puppet_theater/tools.py`](../puppet_theater/tools.py))
+
+- [`ALLOWED_TOOL_NAMES`](../puppet_theater/tools.py) — allowlist: `inspect_prop`, `consult_stage_oracle`, `change_lighting`.
+- [`validate_tool_request`](../puppet_theater/tools.py) — Pydantic + argument shape checks.
+- [`run_actor_tool_request`](../puppet_theater/tools.py) — traces `tool_requested` / `tool_ignored` / `tool_executed` / `tool_result`, updates `session.latest_tool_result` and `recent_tool_results`.
+
+### Trace ([`puppet_theater/trace.py`](../puppet_theater/trace.py))
+
+- [`add_trace_event`](../puppet_theater/trace.py) — appends sanitized dicts to `session.trace_events` (no secrets; path stripping in [`sanitize_value`](../puppet_theater/trace.py)). Each event uses the key **`event_type`** (not `type`) for the event name string.
+- [`export_trace`](../puppet_theater/trace.py) / [`render_trace_json`](../puppet_theater/trace.py) / [`write_trace_json_file`](../puppet_theater/trace.py) — used by the UI for download and display.
+
+**Checkpoint:** If you add a new `event_type` in `add_trace_event`, you can find it in the trace JSON and in Gradio components wired to `render_trace`.
+
+---
+
+## Phase 6: Gradio UI wiring (`app.py`)
+
+Do **not** read [`app.py`](../app.py) top to bottom (it is large). Use this map.
+
+### `gr.Blocks` handlers → Python wrappers → `puppet_theater`
+
+| UI control | Handler in `app.py` | Calls into `puppet_theater` |
+|------------|---------------------|-----------------------------|
+| Create show | [`create_show`](../app.py) (~2607) | [`create_show_from_premise`](../puppet_theater/session.py) |
+| Run one beat | [`advance_one_beat`](../app.py) (~2691) | [`run_one_beat`](../puppet_theater/director.py) (after [`apply_backend_selection`](../app.py)) |
+| Run full act | [`advance_full_act`](../app.py) (~2720) | Loop / yield calling [`run_one_beat`](../puppet_theater/director.py) |
+| Throw prop | [`throw_audience_prop`](../app.py) (~2790) | [`throw_prop`](../puppet_theater/actions.py) |
+| Summon actor | [`summon_audience_actor`](../app.py) (~2820) | [`summon_actor`](../puppet_theater/actions.py) |
+| Request finale | [`request_audience_finale`](../app.py) (~2850) | [`request_finale`](../puppet_theater/actions.py) |
+| Warm up OpenBMB | [`warm_up_backend`](../app.py) (~2879) | [`warm_up_openbmb`](../puppet_theater/backends.py) |
+| Reset | [`reset_show`](../app.py) (~2663) | Clears state (no package call) |
+
+Event wiring lives near **`create_button.click`**, **`run_one_button.click`**, etc. (~3119–3290 in `app.py` at time of writing; line numbers may shift).
+
+Shared presentation pipeline: [`render_outputs`](../app.py) (~2590) refreshes stage HTML, transcript, TTS payload, director log, trace, backend panel.
+
+**Checkpoint:** Name the handler that runs when **Run One Beat** is clicked and the single core engine function it invokes.
+
+---
+
+## Phase 7: Verify and contribute
+
+### Commands
+
+```bash
+uv run python -m py_compile app.py puppet_theater/*.py
+uv run pytest
+```
+
+### Tests to read first
+
+- [`tests/test_director.py`](../tests/test_director.py) — Director and beat behavior.
+- [`tests/conftest.py`](../tests/conftest.py) — shared fixtures.
+
+### First contribution ideas
+
+- Copyedit a `director_log` string.
+- Extend deterministic dialogue or stage effects in [`backends.py`](../puppet_theater/backends.py) / [`director.py`](../puppet_theater/director.py).
+- Add a trace field or a test for a prop-heavy beat.
+- Document an env var in [README.md](../README.md).
+
+### Optional advanced track
+
+[`finetune/`](../finetune/) — LoRA training and eval scripts; separate from the live Gradio beat loop.
+
+---
+
+## Suggested schedule
+
+| Week | Focus |
+|------|--------|
+| 1 | Phases 0–2 + UI play |
+| 2 | Phase 3 (`run_one_beat`) until you can draw the diagram from memory |
+| 3 | Phases 4–5 |
+| 4 | Phase 6–7 + a small PR |
+
+---
+
+## External references
+
+- Gradio **Blocks** and `.click()` inputs/outputs.
+- Pydantic v2 **validators** (`field_validator`).
+- Hugging Face **Spaces** environment variables (see README Configuration).

puppet_theater/actions.py

@@ -1,11 +1,27 @@
+# This file defines "audience interaction" functions for the puppet theater system.
+# These functions allow external inputs (like audience actions) to modify an active TheaterSession,
+# such as throwing props, summoning actors, or requesting the finale.
+
 from puppet_theater.models import Actor, TheaterSession
+from puppet_theater.show_bible import resolve_summoned_actor_via_llm_or_default
 from puppet_theater.trace import add_trace_event
 
 
+# Maximum number of actors allowed on stage at any time
 MAX_ACTORS = 4
 
 
 def throw_prop(session: TheaterSession | None, prop_name: str) -> TheaterSession | None:
+    """
+    Simulates an audience member throwing a prop onto the stage.
+
+    What it does:
+    - Cleans up the prop name (removes extra spaces)
+    - Adds it to the session's props list
+    - Records it as the latest prop and audience action
+    - Updates director logs
+    - Emits a trace event for analytics/debugging
+    """
     if session is None:
         return None
 
@@ -25,10 +41,22 @@ def throw_prop(session: TheaterSession | None, prop_name: str) -> TheaterSession
 
 
 def summon_actor(session: TheaterSession | None, actor_name: str) -> TheaterSession | None:
+    """
+    Allows the audience to summon a new actor onto the stage.
+
+    Behavior:
+    - Cleans the actor name
+    - Checks if stage has space (MAX_ACTORS limit)
+    - If full, logs a "skipped" action
+    - Otherwise creates a new Actor and adds them to the session
+    - Records the action in logs and trace system
+    """
     if session is None:
         return None
 
     name = " ".join(actor_name.strip().split()) or "Mystery Guest"
+
+    # Prevent adding too many actors beyond stage limit
     if len(session.actors) >= MAX_ACTORS:
         session.latest_audience_action = "Audience tried to summon an actor, but the stage is full."
         session.director_log.append(session.latest_audience_action)
@@ -42,38 +70,56 @@ def summon_actor(session: TheaterSession | None, actor_name: str) -> TheaterSess
         )
         return session
 
-    actor = Actor(
-        name=name,
-        avatar="✨",
-        goal="Make the scene stranger without derailing the finale.",
-        secret="Arrived with one completely unexplained cue.",
-        speaking_style="fresh, eager, and just a little too dramatic",
-        tools=["consult_stage_oracle"],
+    actor, summon_llm_source, summon_llm_fallback_used = resolve_summoned_actor_via_llm_or_default(
+        session, name
     )
     session.actors.append(actor)
-    session.latest_audience_action = f"Audience summoned {name}."
+
+    session.latest_audience_action = f"Audience summoned {actor.name}."
     session.director_log.append(session.latest_audience_action)
+    if summon_llm_source:
+        session.director_log.append(
+            f"Summoned puppet profile from {summon_llm_source} (avatar {actor.avatar!s}, tools: {', '.join(actor.tools)})."
+        )
+    elif summon_llm_fallback_used:
+        session.director_log.append(
+            "Summon LLM did not return usable JSON; used built-in guest puppet profile instead."
+        )
+
     add_trace_event(
         session,
         "audience_action",
         audience_action="summon_actor",
-        summoned_actor=name,
+        summoned_actor=actor.name,
+        summon_llm_source=summon_llm_source or "built_in",
+        summon_llm_fallback_used=summon_llm_fallback_used,
         action_summary=session.latest_audience_action,
     )
+
     return session
 
 
 def request_finale(session: TheaterSession | None) -> TheaterSession | None:
+    """
+    Marks the session as having a requested finale.
+
+    What it does:
+    - Sets finale_requested flag to True
+    - Updates latest audience action and director logs
+    - Emits a trace event for analytics/debugging
+    """
     if session is None:
         return None
 
     session.finale_requested = True
     session.latest_audience_action = "Audience requested the finale."
     session.director_log.append(session.latest_audience_action)
+
     add_trace_event(
         session,
         "audience_action",
         audience_action="request_finale",
         action_summary=session.latest_audience_action,
     )
-    return session
+
+    return session

puppet_theater/backdrop_gen.py

@@ -0,0 +1,130 @@
+"""
+Generate a stage backdrop image from the session `setting` sentence via Hugging Face Inference (text-to-image).
+
+The image prompt is built from the setting text (the narrative stage description), plus a short prefix so
+the result stays wide, puppet-friendly, and low-clutter. Output is a JPEG data URL for use in CSS
+`background-image: url(...)`.
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+import logging
+import os
+from typing import Any
+
+from puppet_theater.backends import _hf_api_token
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_T2I_MODEL = "black-forest-labs/FLUX.1-schnell"
+_DEFAULT_T2I_TIMEOUT = 90.0
+_MAX_SETTING_CHARS = 900
+_MAX_OUTPUT_WIDTH = 1152
+
+
+def setting_backdrop_t2i_enabled() -> bool:
+    """When True, premise flow prefers HF text-to-image from `setting` over stock URL LLM (see session)."""
+    raw = os.getenv("HF_SETTING_BACKDROP_IMAGE", "1").strip().lower()
+    if raw in {"0", "false", "no", "off"}:
+        return False
+    return bool(_hf_api_token())
+
+
+def build_setting_text_to_image_prompt(setting: str) -> str:
+    """Compose the text-to-image prompt from the show setting (f-string over setting text)."""
+    s = " ".join(setting.strip().split())
+    if len(s) > _MAX_SETTING_CHARS:
+        s = s[:_MAX_SETTING_CHARS].rsplit(" ", 1)[0].rstrip(",;:")
+    return (
+        "Wide cinematic 16:9 stage backdrop for puppet theater. "
+        "Soft painterly or photographic look, cohesive mood, gentle depth. "
+        "Keep the center area calm and visually simple so puppets in the foreground stay readable. "
+        "No text, no watermark, no logos, no UI, no subtitles. "
+        f"Scene and atmosphere: {s}"
+    )
+
+
+def try_setting_backdrop_data_url(setting: str) -> tuple[str | None, dict[str, Any]]:
+    """
+    Call HF text-to-image with prompt derived from `setting`. Returns (data URL or None, metadata dict).
+    """
+    meta: dict[str, Any] = {"model": os.getenv("HF_BACKDROP_T2I_MODEL", _DEFAULT_T2I_MODEL).strip() or _DEFAULT_T2I_MODEL}
+    if not setting_backdrop_t2i_enabled():
+        meta["skipped"] = "disabled_or_no_token"
+        return None, meta
+    token = _hf_api_token()
+    if not token:
+        meta["skipped"] = "no_token"
+        return None, meta
+
+    prompt = build_setting_text_to_image_prompt(setting)
+    meta["prompt_char_len"] = len(prompt)
+    neg = (
+        "text, watermark, signature, logo, subtitle, ui, frame, border, "
+        "dense crowd, many faces, extreme clutter, harsh noise"
+    )
+
+    timeout = float(os.getenv("HF_BACKDROP_T2I_TIMEOUT", str(_DEFAULT_T2I_TIMEOUT)))
+    timeout = max(15.0, min(timeout, 180.0))
+
+    try:
+        from huggingface_hub import InferenceClient
+        from PIL import Image
+    except ImportError as exc:
+        meta["error"] = f"missing_dependency:{exc}"
+        return None, meta
+
+    client = InferenceClient(token=token, timeout=timeout)
+    model = str(meta["model"])
+
+    try:
+        image = client.text_to_image(
+            prompt,
+            negative_prompt=neg,
+            model=model,
+            width=1152,
+            height=648,
+        )
+    except Exception as first:
+        meta["first_try_error"] = str(first)[:400]
+        try:
+            image = client.text_to_image(prompt, negative_prompt=neg, model=model)
+        except Exception as second:
+            meta["error"] = str(second)[:500]
+            logger.warning("setting_backdrop_t2i: failed model=%r err=%s", model, meta["error"])
+            return None, meta
+
+    if not isinstance(image, Image.Image):
+        meta["error"] = "unexpected_image_type"
+        return None, meta
+
+    image = image.convert("RGB")
+    w, h = image.size
+    if w > _MAX_OUTPUT_WIDTH and w > 0:
+        nh = max(1, int(h * (_MAX_OUTPUT_WIDTH / float(w))))
+        image = image.resize((_MAX_OUTPUT_WIDTH, nh), Image.Resampling.LANCZOS)
+
+    buf = io.BytesIO()
+    image.save(buf, format="JPEG", quality=86, optimize=True)
+    raw = buf.getvalue()
+    meta["jpeg_bytes"] = len(raw)
+    b64 = base64.standard_b64encode(raw).decode("ascii")
+    data_url = f"data:image/jpeg;base64,{b64}"
+    meta["ok"] = True
+    logger.info(
+        "setting_backdrop_t2i: ok model=%r jpeg_bytes=%s",
+        model,
+        meta["jpeg_bytes"],
+    )
+    return data_url, meta
+
+
+def backdrop_url_for_trace(url: str | None) -> str:
+    """Avoid megabyte-long data URLs inside trace JSON."""
+    if not url:
+        return ""
+    if url.startswith("data:image"):
+        return "data:image/jpeg;base64,...(generated)"
+    return url[:400]

puppet_theater/backends.py

@@ -22,6 +22,15 @@ DEFAULT_HF_API_MODEL_ID = DEFAULT_HF_API_MODEL
 OPENBMB_MAX_NEW_TOKENS = 80
 OPENBMB_TEMPERATURE = 0.8
 HF_API_ACTOR_MAX_TOKENS = 120
+# Show-bible JSON (title, setting, 3 roles, URLs) needs a much larger completion budget than one actor line.
+HF_API_SHOW_BIBLE_MAX_TOKENS = int(os.getenv("HF_API_SHOW_BIBLE_MAX_TOKENS", "1024"))
+HF_API_SHOW_BIBLE_MAX_TOKENS = max(256, min(HF_API_SHOW_BIBLE_MAX_TOKENS, 4096))
+# Summoned single-actor JSON is smaller than full show bible but still needs headroom vs actor-line defaults.
+HF_API_SUMMON_ACTOR_MAX_TOKENS = int(os.getenv("HF_API_SUMMON_ACTOR_MAX_TOKENS", "512"))
+HF_API_SUMMON_ACTOR_MAX_TOKENS = max(128, min(HF_API_SUMMON_ACTOR_MAX_TOKENS, 1024))
+
+HF_API_BACKDROP_URL_MAX_TOKENS = int(os.getenv("HF_API_BACKDROP_URL_MAX_TOKENS", "256"))
+HF_API_BACKDROP_URL_MAX_TOKENS = max(64, min(HF_API_BACKDROP_URL_MAX_TOKENS, 512))
 HF_API_DIRECTOR_MAX_TOKENS = 180
 HF_API_ACTOR_TEMPERATURE = 0.75
 HF_API_DIRECTOR_TEMPERATURE = 0.35
@@ -362,6 +371,7 @@ class HFAPIBackend(ModelBackend):
         *,
         max_tokens: int | None = None,
         temperature: float | None = None,
+        system_message: str | None = None,
     ) -> str:
         token = _hf_api_token()
         if not token:
@@ -378,13 +388,15 @@ class HFAPIBackend(ModelBackend):
             raise RuntimeError("huggingface_hub is not installed") from exc
 
         client = InferenceClient(token=token, timeout=self.timeout_seconds)
+        sys_content = system_message or "You are a puppet theater generation backend. Return valid JSON only."
+
         try:
             output = client.chat.completions.create(
                 model=self.model_id,
                 messages=[
                     {
                         "role": "system",
-                        "content": "You are a puppet theater generation backend. Return valid JSON only.",
+                        "content": sys_content,
                     },
                     {"role": "user", "content": prompt},
                 ],

puppet_theater/director.py

@@ -1,3 +1,7 @@
+# This file is the core “director + runtime engine” of the puppet theater system.
+# It controls story progression, selects speakers, validates AI decisions,
+# runs one beat at a time, and manages both deterministic and LLM-based directors.
+
 from collections import Counter
 from dataclasses import dataclass
 import json
@@ -21,6 +25,7 @@ from puppet_theater.trace import add_trace_event
 from puppet_theater.tools import run_actor_tool_request
 
 
+# Allowed narrative beats (types of actions that can happen in the story)
 BEAT_ARC = [
     "setup",
     "denial_or_contradiction",
@@ -30,15 +35,18 @@ BEAT_ARC = [
     "finale",
 ]
 
+# High-level story phases derived from progress
 STORY_PHASES = ["opening", "complication", "reveal", "chaos", "finale"]
 
 
 def story_progress(session: TheaterSession) -> float:
+    # Returns normalized progress (0.0 to 1.0) based on beat progression
     target_beats = max(1, session.target_beats)
     return min(1.0, max(0.0, session.beat_index / target_beats))
 
 
 def story_phase(session: TheaterSession) -> str:
+    # Converts numeric progress into narrative phase buckets
     progress = story_progress(session)
     if progress < 0.20:
         return "opening"
@@ -52,6 +60,7 @@ def story_phase(session: TheaterSession) -> str:
 
 
 def should_force_finale(session: TheaterSession) -> bool:
+    # Determines if story should end early due to constraints or user request
     return (
         session.finale_requested
         or session.beat_index >= session.target_beats - 1
@@ -61,6 +70,7 @@ def should_force_finale(session: TheaterSession) -> bool:
 
 @dataclass(frozen=True)
 class DirectorGeneration:
+    # Wrapper around a director decision plus metadata about how it was generated
     decision: DirectorDecision
     director_mode: str
     model_id: str | None
@@ -72,9 +82,12 @@ class DirectorGeneration:
 
 
 class DirectorPolicy:
+    # Deterministic rule-based director (fallback when no AI is used)
     def decide(self, session: TheaterSession) -> DirectorDecision:
         phase = story_phase(session)
         progress = story_progress(session)
+
+        # Force finale conditions override everything else
         if should_force_finale(session):
             speaker = self._choose_speaker(session)
             return DirectorDecision(
@@ -86,6 +99,7 @@ class DirectorPolicy:
                 reason_summary="Finale requested, target reached, or final beat reached; closing cleanly.",
             )
 
+        # Audience prop takes priority in narrative
         if session.latest_prop is not None:
             speaker = self._choose_speaker(session)
             return DirectorDecision(
@@ -97,6 +111,7 @@ class DirectorPolicy:
                 reason_summary=f"Latest audience prop {session.latest_prop} should affect the next beat.",
             )
 
+        # Newly summoned actors should get priority spotlight
         summoned_actor = self._unused_summoned_actor(session)
         if summoned_actor is not None:
             return DirectorDecision(
@@ -107,9 +122,11 @@ class DirectorPolicy:
                 reason_summary=f"Newly summoned actor {summoned_actor.name} has not spoken yet.",
             )
 
+        # Default storytelling logic based on phase
         beat_type = self._beat_type_for_phase(phase, session)
         speaker = self._choose_speaker(session)
         reveal_secret = beat_type == "secret_reveal"
+
         return DirectorDecision(
             next_speaker=speaker.name,
             beat_type=beat_type,
@@ -121,16 +138,20 @@ class DirectorPolicy:
         )
 
     def _choose_speaker(self, session: TheaterSession) -> Actor:
+        # Picks next actor fairly based on usage + rotation
         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:
+        # Returns summoned actors who haven't spoken yet
         spoken = {beat.speaker for beat in session.transcript}
         for actor in session.actors[3:]:
             if actor.name not in spoken:
@@ -138,6 +159,7 @@ class DirectorPolicy:
         return None
 
     def _instruction_for_beat(self, beat_type: str, reveal_secret: bool) -> str:
+        # Maps beat type to actor instruction
         if reveal_secret:
             return "Reveal your secret directly, but keep it playful and stage-ready."
         return {
@@ -149,6 +171,7 @@ class DirectorPolicy:
         }.get(beat_type, "Keep the scene moving with one short line.")
 
     def _effect_for_beat(self, beat_type: str) -> str:
+        # Maps beat type to stage visual effect
         return {
             "setup": "warm_spotlight",
             "denial_or_contradiction": "quick_blackout",
@@ -159,6 +182,7 @@ class DirectorPolicy:
         }[beat_type]
 
     def _beat_type_for_phase(self, phase: str, session: TheaterSession) -> str:
+        # Chooses beat type based on story phase progression
         if phase == "opening":
             return "setup" if session.beat_index == 0 else "denial_or_contradiction"
         if phase == "complication":
@@ -171,6 +195,7 @@ class DirectorPolicy:
 
 
 class OpenBMBDirectorPolicy:
+    # Director powered by OpenBMB transformer backend
     def __init__(self, fallback_policy: DirectorPolicy | None = None) -> None:
         self.fallback_policy = fallback_policy or DirectorPolicy()
 
@@ -181,16 +206,19 @@ class OpenBMBDirectorPolicy:
             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,
@@ -202,11 +230,13 @@ class OpenBMBDirectorPolicy:
                 latency_ms=_elapsed_ms(start_time),
             )
 
+        # Repair attempt when output is invalid
         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:
@@ -219,6 +249,7 @@ class OpenBMBDirectorPolicy:
             )
 
         decision, repair_status = parse_director_decision(repair_output, session)
+
         if decision is not None:
             return DirectorGeneration(
                 decision=decision,
@@ -259,6 +290,7 @@ class OpenBMBDirectorPolicy:
 
 
 class HFAPIDirectorPolicy:
+    # Director using HuggingFace API backend
     def __init__(self, fallback_policy: DirectorPolicy | None = None) -> None:
         self.fallback_policy = fallback_policy or DirectorPolicy()
 
@@ -269,10 +301,12 @@ class HFAPIDirectorPolicy:
             max_new_tokens=HF_API_DIRECTOR_MAX_TOKENS,
             temperature=HF_API_DIRECTOR_TEMPERATURE,
         )
+
         if not isinstance(backend, HFAPIBackend):
             return self._fallback(session, "backend_unavailable", start_time)
 
         prompt = build_director_prompt(session)
+
         try:
             raw_output = backend._generate_text(
                 prompt,
@@ -285,6 +319,7 @@ class HFAPIDirectorPolicy:
             return generation
 
         decision, validation_status = parse_director_decision(raw_output, session)
+
         if decision is not None:
             generation = DirectorGeneration(
                 decision=decision,
@@ -303,6 +338,7 @@ class HFAPIDirectorPolicy:
             "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,
@@ -321,6 +357,7 @@ class HFAPIDirectorPolicy:
             return generation
 
         decision, repair_status = parse_director_decision(repair_output, session)
+
         if decision is not None:
             generation = DirectorGeneration(
                 decision=decision,
@@ -365,10 +402,12 @@ class HFAPIDirectorPolicy:
 
 
 def choose_director_decision(session: TheaterSession) -> DirectorGeneration:
+    # Router that selects deterministic vs AI directors
     if session.director_mode == "hf_api":
         return HFAPIDirectorPolicy().decide(session)
     if session.director_mode == "openbmb":
         return OpenBMBDirectorPolicy().decide(session)
+
     decision = DirectorPolicy().decide(session)
     return DirectorGeneration(
         decision=decision,
@@ -382,6 +421,7 @@ def choose_director_decision(session: TheaterSession) -> DirectorGeneration:
 
 
 def run_one_beat(session: TheaterSession | None) -> TheaterSession | None:
+    # Executes one full story cycle: director → actor → state update → logs
     if session is None:
         return None
 
@@ -397,10 +437,13 @@ def run_one_beat(session: TheaterSession | None) -> TheaterSession | None:
 
     current_phase = story_phase(session)
     current_progress = story_progress(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:
         speaker.held_prop = prop
 
@@ -408,18 +451,22 @@ 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(
         f"Story phase {current_phase} at {current_progress:.0%} progress "
         f"(min={session.min_beats}, target={session.target_beats}, max={session.max_beats})."
     )
+
     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}.")
     add_trace_event(
@@ -467,6 +514,7 @@ def run_one_beat(session: TheaterSession | None) -> TheaterSession | None:
         )
 
     backend_generation = generate_actor_response(session, decision, speaker, prop)
+
     session.beat_index += 1
 
     response = backend_generation.response
@@ -480,9 +528,13 @@ def run_one_beat(session: TheaterSession | None) -> TheaterSession | None:
         memory_update=response.memory_update,
         tool_request=response.tool_request,
     )
+
     session.transcript.append(beat)
+
     state_update = apply_actor_state_update(session, speaker, response, decision, prop)
+
     tool_result = run_actor_tool_request(session, speaker, response.tool_request)
+
     if tool_result is not None and tool_result.stage_effect:
         beat.stage_effect = tool_result.stage_effect
 
@@ -599,15 +651,18 @@ def run_one_beat(session: TheaterSession | None) -> TheaterSession | None:
 
 
 def run_full_act(session: TheaterSession | None) -> TheaterSession | None:
+    # Runs the full play until completion
     if session is None:
         return None
 
     while session.beat_index < session.max_beats:
         run_one_beat(session)
+
     return session
 
 
 def _actor_by_name(session: TheaterSession, actor_name: str) -> Actor:
+    # Lookup actor safely, fallback to rotation if missing
     for actor in session.actors:
         if actor.name == actor_name:
             return actor
@@ -621,6 +676,7 @@ def apply_actor_state_update(
     decision: DirectorDecision,
     prop: str | None,
 ) -> dict[str, str]:
+    # Updates actor state: mood, memory, secret status, goals
     intent = _short_public_text(getattr(response, "intent", "") or "Respond to the Director's cue.", speaker, 90)
     memory_update = _short_public_text(getattr(response, "memory_update", "") or "", speaker, 140)
     emotion = _short_public_text(getattr(response, "emotion", "") or "focused", speaker, 40)
@@ -649,6 +705,7 @@ def apply_actor_state_update(
 
 
 def build_director_prompt(session: TheaterSession) -> str:
+    # Builds LLM prompt with full story context
     actor_profiles = "\n".join(
         "- "
         f"{actor.name}: goal={actor.goal}; style={actor.speaking_style}; "

puppet_theater/models.py

@@ -6,6 +6,27 @@ from typing import Any, Literal
 
 from pydantic import BaseModel, Field, ValidationInfo, field_validator
 
+"""
+Core data models for the puppet theater simulation.
+
+This module defines the structured objects used throughout a theater session,
+including:
+
+- Actors and their state (goals, secrets, mood, props, memory)
+- Director decisions that guide story progression
+- Actor responses for each scene beat
+- Tool requests and tool execution results
+- Individual beats in the transcript
+- The overall theater session state and configuration
+
+Pydantic models are used where validation is required for LLM-generated
+outputs (e.g. actor responses and director decisions), while dataclasses
+are used for runtime session state and domain entities.
+
+In short: this file defines the data structures that represent the
+story, characters, dialogue, stage actions, and session state of
+the puppet theater engine.
+"""
 
 BeatType = Literal[
     "setup",
@@ -21,6 +42,13 @@ SimpleToolValue = str | int | float | bool | None
 
 
 class ToolRequest(BaseModel):
+    """
+    Represents a request to call a tool.
+
+    Pydantic automatically validates the input data when an
+    instance is created. Ensures the tool name and reason are
+    non-empty and that the reason remains concise.
+    """
     tool_name: str
     arguments: Any = Field(default_factory=dict)
     reason: str
@@ -42,6 +70,21 @@ class ToolRequest(BaseModel):
 
 
 class ActorResponse(BaseModel):
+    """
+    Represents a structured response from a puppet actor for one scene beat.
+
+    Includes:
+    - intent: actor's short goal for this beat
+    - line: dialogue spoken on stage
+    - emotion: actor's emotional state
+    - gesture: physical action performed
+    - stage_effect: environmental/stage effect
+    - memory_update: optional note carried to future beats
+    - tool_request: optional request to use a tool
+
+    Validators enforce length limits, remove extra whitespace,
+    and prevent required fields from being empty.
+    """
     intent: str = Field(default="Keep the scene moving.", description="Short visible actor intention.")
     line: str = Field(description="Short, stage-ready puppet dialogue.")
     emotion: str
@@ -113,11 +156,12 @@ class DirectorDecision(BaseModel):
 @dataclass
 class Actor:
     name: str
-    avatar: str
+    avatar: str  # Emoji or short label; used if avatar_image_url is unset/invalid.
     goal: str
     secret: str
     speaking_style: str
     tools: list[str] = field(default_factory=list)
+    avatar_image_url: str | None = None  # Optional HTTPS portrait for the stage card.
     held_prop: str | None = None
     mood: str = "ready"
     current_goal: str | None = None
@@ -155,6 +199,8 @@ class TheaterSession:
     premise: str
     setting: str
     actors: list[Actor]
+    backdrop_image_url: str | None = None  # Optional HTTPS image layered behind stage copy.
+    backdrop_description: str | None = None  # LLM minimal art-direction text used to pick backdrop_image_url.
     session_id: str = field(default_factory=lambda: uuid4().hex[:12])
     created_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
     beat_index: int = 0

puppet_theater/session.py

@@ -1,16 +1,45 @@
+# This file builds a "puppet theater show session" from a given story premise.
+# It converts a short idea (premise) into a structured theatrical session with actors,
+# a setting, and metadata used to simulate a puppet show performance.
+
+import logging
+
 from puppet_theater.models import Actor, TheaterSession
+from puppet_theater.backdrop_gen import (
+    backdrop_url_for_trace,
+    setting_backdrop_t2i_enabled,
+    try_setting_backdrop_data_url,
+)
+from puppet_theater.show_bible import (
+    invoke_show_bible_llm,
+    llm_backend_order,
+    parse_show_bible_response,
+    resolve_backdrop_image_url_via_llm,
+)
 from puppet_theater.trace import add_trace_event
 
+logger = logging.getLogger(__name__)
 
+# These are predefined show length configurations.
+# Each tuple represents: (minimum beats, target beats, maximum beats)
+# "beats" can be thought of as story steps or scene turns in the puppet show.
 SHOW_LENGTH_PRESETS: dict[str, tuple[int, int, int]] = {
     "short": (5, 7, 8),
     "standard": (7, 10, 12),
     "extended": (10, 14, 16),
 }
+
+# Default show length used when no preference is provided
 DEFAULT_SHOW_LENGTH = "standard"
 
 
 def resolve_show_length(show_length: str | None = None) -> tuple[str, int, int, int]:
+    """
+    Converts a show length label (like "short", "standard", "extended")
+    into actual numeric constraints (min, target, max beats).
+
+    If the input is invalid or None, it falls back to DEFAULT_SHOW_LENGTH.
+    """
     normalized = (show_length or DEFAULT_SHOW_LENGTH).strip().lower()
     if normalized not in SHOW_LENGTH_PRESETS:
         normalized = DEFAULT_SHOW_LENGTH
@@ -19,11 +48,25 @@ def resolve_show_length(show_length: str | None = None) -> tuple[str, int, int,
 
 
 def _clean_premise(premise: str) -> str:
+    """
+    Cleans up the input premise by removing extra spaces and normalizing it.
+    If the premise is empty after cleanup, returns a fallback default story idea.
+    """
     cleaned = " ".join(premise.strip().split())
     return cleaned or "A mysterious puppet show with no premise"
 
 
 def _title_from_premise(premise: str) -> str:
+    """
+    Generates a show title based on important words from the premise.
+
+    - Splits the premise into words
+    - Removes punctuation
+    - Picks words longer than 3 characters
+    - Capitalizes them and uses up to 4 words for the title
+
+    If no good words exist, returns a default title.
+    """
     words = [word.strip(".,!?;:()[]{}\"'") for word in premise.split()]
     keywords = [word.title() for word in words if len(word.strip(".,!?;:()[]{}\"'")) > 3]
     if not keywords:
@@ -32,6 +75,16 @@ def _title_from_premise(premise: str) -> str:
 
 
 def _setting_from_premise(premise: str) -> str:
+    """
+    Chooses a stage setting based on keywords in the premise.
+
+    This is a simple rule-based system:
+    - space/moon/star → space-themed stage
+    - castle/dragon/wizard → fantasy castle stage
+    - detective/mystery → noir detective setting
+    - kitchen/chef/toaster → kitchen stage
+    - otherwise → generic puppet stage
+    """
     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"
@@ -44,21 +97,110 @@ 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,
-    backend_max_new_tokens: int = 120,
-    backend_temperature: float = 0.75,
-    director_mode: str = "deterministic",
-    show_length: str = DEFAULT_SHOW_LENGTH,
-) -> TheaterSession:
-    cleaned_premise = _clean_premise(premise)
-    show_title = _title_from_premise(cleaned_premise)
-    setting = _setting_from_premise(cleaned_premise)
-    active_show_length, min_beats, target_beats, max_beats = resolve_show_length(show_length)
+# Wide Unsplash images (curated IDs) used only when the LLM omits or invalidates backdrop_image_url
+# (see create_show_from_premise: llm_backdrop_url or keyword fallback).
+_DEFAULT_BACKDROP_URL = (
+    "https://images.unsplash.com/photo-1578662996442-48f60103fc96"
+    "?auto=format&fit=crop&w=1600&q=80"
+)
+
+_BACKDROP_RULES: tuple[tuple[tuple[str, ...], str], ...] = (
+    (
+        (
+            "moon",
+            "space",
+            "star",
+            "orbit",
+            "galaxy",
+            "mars",
+            "alien",
+            "planet",
+            "rocket",
+            "astronaut",
+            "comet",
+            "lunar",
+            "cosmos",
+        ),
+        "https://images.unsplash.com/photo-1516339901601-2e1b62dc0c45?auto=format&fit=crop&w=1600&q=80",
+    ),
+    (
+        ("kitchen", "cook", "chef", "toast", "oven", "recipe", "pan", "stove", "fridge", "cupcake", "tea"),
+        "https://images.unsplash.com/photo-1556912173-3c541015bf3b?auto=format&fit=crop&w=1600&q=80",
+    ),
+    (
+        ("castle", "dragon", "wizard", "knight", "sword", "enchant", "fairy", "throne", "dungeon"),
+        "https://images.unsplash.com/photo-1518173946689-a94480f4bd0e?auto=format&fit=crop&w=1600&q=80",
+    ),
+    (
+        (
+            "detective",
+            "mystery",
+            "noir",
+            "crime",
+            "alley",
+            "shadow",
+            "clue",
+            "murder",
+            "case file",
+            "interrogat",
+        ),
+        "https://images.unsplash.com/photo-1428908728789-d2de25dbd4e0?auto=format&fit=crop&w=1600&q=80",
+    ),
+    (
+        ("ocean", "sea", "beach", "wave", "sail", "island", "submarine", "whale", "harbor", "pirate"),
+        "https://images.unsplash.com/photo-1505118380757-91f5f5632ce0?auto=format&fit=crop&w=1600&q=80",
+    ),
+    (
+        ("forest", "wood", "tree", "cabin", "hike", "camp", "bear", "owl", "moss"),
+        "https://images.unsplash.com/photo-1448375260088-37575c2fbe04?auto=format&fit=crop&w=1600&q=80",
+    ),
+    (
+        ("school", "classroom", "student", "teacher", "homework", "blackboard", "campus"),
+        "https://images.unsplash.com/photo-1580582932707-520aed937a7e?auto=format&fit=crop&w=1600&q=80",
+    ),
+    (
+        ("library", "book", "scroll", "archive", "museum", "gallery"),
+        "https://images.unsplash.com/photo-1507842217343-303bb9a4036a?auto=format&fit=crop&w=1600&q=80",
+    ),
+    (
+        ("circus", "carnival", "tent", "acrobat", "clown", "trapeze"),
+        "https://images.unsplash.com/photo-1508807526345-15e9b5f4eaff?auto=format&fit=crop&w=1600&q=80",
+    ),
+    (
+        ("desert", "cactus", "dune", "mirage", "oasis"),
+        "https://images.unsplash.com/photo-1509316785289-025f5b846b35?auto=format&fit=crop&w=1600&q=80",
+    ),
+    (
+        ("winter", "snow", "blizzard", "frost", "igloo", "icicle", "snowfall"),
+        "https://images.unsplash.com/photo-1519681393784-d120267933ba?auto=format&fit=crop&w=1600&q=80",
+    ),
+    (
+        ("hospital", "doctor", "nurse", "clinic", "surgery", "medic"),
+        "https://images.unsplash.com/photo-1519494026892-80bbd2d6fd0d?auto=format&fit=crop&w=1600&q=80",
+    ),
+    (
+        ("train", "station", "locomotive", "railway", "subway"),
+        "https://images.unsplash.com/photo-1474487548417-781cb71445bb?auto=format&fit=crop&w=1600&q=80",
+    ),
+)
+
+
+def _backdrop_url_from_premise_and_setting(premise: str, setting: str) -> str:
+    """
+    Fallback when the show bible did not yield a usable backdrop_image_url.
+
+    Matches keywords in premise + setting and returns a curated wide image, else _DEFAULT_BACKDROP_URL.
+    """
+    hay = f"{premise} {setting}".lower()
+    for keywords, url in _BACKDROP_RULES:
+        if any(k in hay for k in keywords):
+            return url
+    return _DEFAULT_BACKDROP_URL
 
-    actors = [
+
+def _default_cast() -> list[Actor]:
+    """Fallback puppets when no LLM cast is available."""
+    return [
         Actor(
             name="Pip the Director",
             avatar="🎬",
@@ -85,23 +227,279 @@ def create_show_from_premise(
         ),
     ]
 
+
+_REMINDER_SUFFIX = (
+    "\n\nReminder: respond with exactly one JSON object using only these top-level keys: "
+    "show_title, setting, backdrop_description, director, puppet_actors. "
+    "backdrop_description: two short sentences, minimal uncluttered background for puppets (see Rules). "
+    "The director and each puppet entry must include name, avatar, goal, secret, speaking_style, tools."
+)
+
+
+def _resolve_show_content_from_llm_or_defaults(
+    cleaned_premise: str,
+    backend_name: str,
+    director_mode: str,
+    backend_max_new_tokens: int,
+    backend_temperature: float,
+) -> tuple[str, str, str | None, list[Actor], str | None, bool, list[dict[str, object]], str | None]:
+    """
+    Returns show_title, setting, backdrop_image_url, actors, llm_source_or_none, cast_fallback_used,
+    cast_attempt_log, and backdrop_description (LLM minimal art direction, or None).
+
+    cast_fallback_used is True only when at least one LLM-capable backend was tried and none
+    returned a valid show bible (so the built-in cast and heuristic title/setting are used).
+    """
+    fallback_title = _title_from_premise(cleaned_premise)
+    fallback_setting = _setting_from_premise(cleaned_premise)
+    default_actors = _default_cast()
+    candidates = llm_backend_order(director_mode, backend_name)
+    attempt_log: list[dict[str, object]] = []
+
+    if not candidates:
+        logger.info(
+            "premise_cast: no LLM backends in order (director_mode=%r backend_name=%r); "
+            "using heuristic title=%r heuristic_setting_chars=%s",
+            director_mode,
+            backend_name,
+            fallback_title,
+            len(fallback_setting),
+        )
+        return fallback_title, fallback_setting, None, default_actors, None, False, attempt_log, None
+
+    logger.info(
+        "premise_cast: trying backends %s (premise_len=%s max_new_tokens=%s temp=%s)",
+        candidates,
+        len(cleaned_premise),
+        backend_max_new_tokens,
+        backend_temperature,
+    )
+
+    for mode in candidates:
+        suffixes: tuple[str, ...] = ("", _REMINDER_SUFFIX) if mode in {"local_lora", "local_gguf"} else ("",)
+        for suffix in suffixes:
+            entry: dict[str, object] = {
+                "backend": mode,
+                "with_schema_reminder": bool(suffix),
+            }
+            try:
+                raw = invoke_show_bible_llm(
+                    mode,
+                    cleaned_premise,
+                    max_new_tokens=backend_max_new_tokens,
+                    temperature=backend_temperature,
+                    extra_user_suffix=suffix,
+                )
+                entry["raw_char_len"] = len(raw)
+                entry["raw_preview"] = raw[:450]
+                parsed = parse_show_bible_response(raw)
+                entry["parsed_ok"] = parsed is not None
+                if parsed is None:
+                    attempt_log.append(entry)
+                    logger.info(
+                        "premise_cast: parse_miss backend=%r reminder=%s raw_len=%s raw_head=%r",
+                        mode,
+                        bool(suffix),
+                        len(raw),
+                        raw[:240],
+                    )
+                    continue
+                title, setting, backdrop_desc, actors = parsed
+                entry["resolved_show_title"] = title
+                entry["resolved_actor_names"] = [a.name for a in actors]
+                entry["backdrop_description"] = (backdrop_desc or "")[:320]
+                if setting_backdrop_t2i_enabled():
+                    entry["backdrop_url_resolution"] = {"deferred": "hf_setting_text_to_image"}
+                    entry["has_backdrop_url"] = False
+                    attempt_log.append(entry)
+                    logger.info(
+                        "premise_cast: ok backend=%r title=%r setting_len=%s actors=%s backdrop_url=deferred_t2i",
+                        mode,
+                        title,
+                        len(setting),
+                        [a.name for a in actors],
+                    )
+                    return title, setting, None, actors, mode, False, attempt_log, backdrop_desc
+                backdrop, bmeta = resolve_backdrop_image_url_via_llm(
+                    mode,
+                    cleaned_premise,
+                    title,
+                    setting,
+                    backdrop_desc or "",
+                    max_new_tokens=backend_max_new_tokens,
+                    temperature=backend_temperature,
+                )
+                entry["backdrop_url_resolution"] = bmeta
+                entry["has_backdrop_url"] = bool(backdrop)
+                attempt_log.append(entry)
+                logger.info(
+                    "premise_cast: ok backend=%r title=%r setting_len=%s actors=%s backdrop_url=%s",
+                    mode,
+                    title,
+                    len(setting),
+                    [a.name for a in actors],
+                    "yes" if backdrop else "no",
+                )
+                return title, setting, backdrop, actors, mode, False, attempt_log, backdrop_desc
+            except Exception as exc:
+                entry["error"] = str(exc)[:500]
+                attempt_log.append(entry)
+                logger.warning(
+                    "premise_cast: exception backend=%r reminder=%s err=%r",
+                    mode,
+                    bool(suffix),
+                    str(exc)[:400],
+                )
+                continue
+
+    logger.warning(
+        "premise_cast: all attempts failed; fallback title=%r actors=%s (see trace premise_cast_resolved)",
+        fallback_title,
+        [a.name for a in default_actors],
+    )
+    return fallback_title, fallback_setting, None, default_actors, None, True, attempt_log, None
+
+
+def create_show_from_premise(
+    premise: str,
+    backend_name: str = "deterministic",
+    backend_model_id: str | None = None,
+    backend_max_new_tokens: int = 120,
+    backend_temperature: float = 0.75,
+    director_mode: str = "deterministic",
+    show_length: str = DEFAULT_SHOW_LENGTH,
+) -> TheaterSession:
+    """
+    Main function that creates a full TheaterSession from a simple premise.
+
+    Steps it performs:
+    1. Cleans the input premise
+    2. Resolves show length into beats (story structure size)
+    3. When director or actor backend is an LLM (hf_api, openbmb, local_lora, local_gguf), asks it for
+       show title, setting, backdrop_description (minimal art direction), and three roles (director + two
+       puppets) with optional portrait URLs. When HF text-to-image is enabled, the backdrop is generated
+       from the setting sentence next; otherwise a second LLM call picks a stock https URL from that
+       description. Deterministic cast uses heuristic title/setting only.
+    4. Backdrop priority: HF text-to-image from `setting` (when enabled + token), else LLM stock URL (if
+       cast succeeded without T2I deferral), else keyword stock images from premise + setting.
+    5. Builds a TheaterSession object with all metadata
+    6. Adds trace events for debugging/analytics
+
+    Returns:
+        TheaterSession: A fully initialized puppet theater session
+    """
+
+    cleaned_premise = _clean_premise(premise)
+    active_show_length, min_beats, target_beats, max_beats = resolve_show_length(show_length)
+
     supported_generation_modes = {"deterministic", "openbmb", "hf_api", "local_lora", "local_gguf"}
     active_backend = backend_name if backend_name in supported_generation_modes else "deterministic"
     active_director_mode = director_mode if director_mode in supported_generation_modes else "deterministic"
+
+    (
+        show_title,
+        setting,
+        llm_backdrop_url,
+        actors,
+        cast_llm_source,
+        cast_fallback_used,
+        cast_attempt_log,
+        backdrop_description,
+    ) = _resolve_show_content_from_llm_or_defaults(
+        cleaned_premise,
+        active_backend,
+        active_director_mode,
+        backend_max_new_tokens,
+        backend_temperature,
+    )
+
+    backdrop_image_url: str | None = None
+    backdrop_image_source = "premise_keyword_fallback"
+    setting_t2i_meta: dict[str, object] | None = None
+
+    if setting_backdrop_t2i_enabled():
+        backdrop_image_url, setting_t2i_meta = try_setting_backdrop_data_url(setting)
+        if backdrop_image_url:
+            backdrop_image_source = "hf_setting_text_to_image"
+
+    if not backdrop_image_url:
+        llm_url = llm_backdrop_url
+        if llm_url is None and cast_llm_source and setting_backdrop_t2i_enabled():
+            llm_url, bmeta = resolve_backdrop_image_url_via_llm(
+                cast_llm_source,
+                cleaned_premise,
+                show_title,
+                setting,
+                backdrop_description or "",
+                max_new_tokens=backend_max_new_tokens,
+                temperature=backend_temperature,
+            )
+            if cast_attempt_log:
+                cast_attempt_log[-1]["backdrop_url_resolution_after_t2i_fail"] = bmeta
+                cast_attempt_log[-1]["has_backdrop_url_after_t2i_fail"] = bool(llm_url)
+        if llm_url:
+            backdrop_image_url = llm_url
+            backdrop_image_source = "llm_from_description"
+        else:
+            backdrop_image_url = _backdrop_url_from_premise_and_setting(cleaned_premise, setting)
+            backdrop_image_source = "premise_keyword_fallback"
+
     model_note = f" ({backend_model_id})" if backend_model_id else ""
+
+    cast_note = (
+        f"Cast and title from {cast_llm_source} show bible."
+        if cast_llm_source
+        else (
+            "Cast and title use built-in defaults (no LLM-capable engine selected for casting)."
+            if not llm_backend_order(active_director_mode, active_backend)
+            else "Cast and title use built-in defaults (LLM show bible failed or was invalid)."
+        )
+    )
+    if backdrop_image_source == "hf_setting_text_to_image":
+        backdrop_note = "Backdrop: HF text-to-image from the setting sentence (wide stage, puppet-safe prompt)."
+    elif backdrop_image_source == "llm_from_description":
+        backdrop_note = "Backdrop: LLM stock image URL from minimal backdrop_description (two-step flow)."
+    else:
+        backdrop_note = "Backdrop: keyword stock image fallback (T2I/URL unavailable or disabled)."
+
+    cast_roll = " · ".join(
+        f"{a.name} ({a.avatar})" + (f" [img]" if a.avatar_image_url else "")
+        for a in actors
+    )
+
+    # Internal log for debugging how the director created the session
     director_log = [
         f"Director created a {active_show_length} show plan.",
         f"Active backend: {active_backend}{model_note}.",
         f"Director mode: {active_director_mode}.",
         f"Show length: min {min_beats}, target {target_beats}, max {max_beats} beats.",
-        f"Setting selected: {setting}.",
+        cast_note,
+        f"Resolved show_title: {show_title}",
+        f"Resolved setting: {setting}",
+        f"Resolved cast: {cast_roll}",
+        f"Premise cast source: {cast_llm_source or 'deterministic/heuristic'}; LLM cast fallback used: {str(cast_fallback_used).lower()}.",
+        (
+            f"Backdrop description (LLM): {backdrop_description}"
+            if backdrop_description
+            else "Backdrop description (LLM): (omitted; URL step used setting text as art direction)."
+        ),
+        backdrop_note,
+        (
+            "Backdrop image: inline JPEG from setting (HF text-to-image)."
+            if (backdrop_image_url or "").startswith("data:image")
+            else f"Backdrop image URL: {backdrop_image_url or '(none)'}"
+        ),
         "Three puppet actors are waiting for the first beat.",
     ]
+
+    # Create the main theater session object that holds the entire show state
     session = TheaterSession(
         show_title=show_title,
         premise=cleaned_premise,
         setting=setting,
         actors=actors,
+        backdrop_image_url=backdrop_image_url,
+        backdrop_description=backdrop_description,
         beat_index=0,
         min_beats=min_beats,
         target_beats=target_beats,
@@ -121,6 +519,29 @@ def create_show_from_premise(
         director_mode=active_director_mode,
         play_opening_curtain=True,
     )
+
+    # Logging trace events for debugging/analytics pipeline
+    add_trace_event(
+        session,
+        "premise_cast_resolved",
+        reason_summary=(
+            f"title={show_title!r}; source={cast_llm_source or 'deterministic'}; "
+            f"fallback={cast_fallback_used}; attempts={len(cast_attempt_log)}"
+        ),
+        resolved_show_title=show_title,
+        resolved_setting=setting,
+        resolved_actor_names=[a.name for a in actors],
+        resolved_actor_avatars=[a.avatar for a in actors],
+        backdrop_image_url=backdrop_url_for_trace(backdrop_image_url),
+        backdrop_image_source=backdrop_image_source,
+        backdrop_description=(backdrop_description or "")[:400],
+        setting_backdrop_t2i=setting_t2i_meta,
+        premise_cast_source=cast_llm_source or "deterministic",
+        cast_fallback_used=cast_fallback_used,
+        cast_attempts=cast_attempt_log,
+        llm_candidate_order=llm_backend_order(active_director_mode, active_backend),
+    )
+
     add_trace_event(
         session,
         "show_created",
@@ -133,9 +554,13 @@ def create_show_from_premise(
         max_beats=max_beats,
         actor_count=len(actors),
         validation_status="valid",
-        fallback_used=False,
+        fallback_used=cast_fallback_used,
+        premise_cast_source=cast_llm_source or "deterministic",
+        backdrop_image_configured=bool(backdrop_image_url),
     )
+
     add_trace_event(session, "actors_created", actor_count=len(actors))
+
     add_trace_event(
         session,
         "director_plan_created",
@@ -143,4 +568,5 @@ def create_show_from_premise(
         story_phase="opening",
         reason_summary=f"{active_show_length.title()} progress-based show plan created.",
     )
-    return session
+
+    return session

puppet_theater/show_bible.py

@@ -0,0 +1,686 @@
+# LLM-assisted "show bible": title, setting, optional backdrop image, director + two puppets.
+# Used at session creation when the director and/or actor backend is an LLM
+# (hf_api, openbmb, local_lora, local_gguf); falls back to deterministic defaults if parsing fails.
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import replace
+from typing import Any
+from urllib.parse import urlparse
+
+from puppet_theater.backends import (
+    HFAPIBackend,
+    HF_API_BACKDROP_URL_MAX_TOKENS,
+    HF_API_SHOW_BIBLE_MAX_TOKENS,
+    HF_API_SUMMON_ACTOR_MAX_TOKENS,
+    LocalGGUFActorBackend,
+    LocalLoRAActorBackend,
+    OpenBMBTransformersBackend,
+    _run_with_timeout,
+    format_chatml,
+    get_backend,
+)
+from puppet_theater.models import Actor, TheaterSession
+from puppet_theater.tools import ALLOWED_TOOL_NAMES
+
+_SHOW_BIBLE_INSTRUCTIONS = """You are casting a three-character puppet improv for "AI Puppet Theater".
+Return ONE compact JSON object only. No markdown. No keys beyond the schema.
+
+Schema:
+{
+  "show_title": "short catchy title, max 8 words",
+  "setting": "one vivid sentence describing the stage backdrop and mood",
+  "backdrop_description": "two short sentences (see Rules)",
+  "director": {
+    "name": "director puppet name (include a playful title)",
+    "avatar": "single emoji",
+    "avatar_image_url": "https portrait URL or empty string",
+    "goal": "one sentence",
+    "secret": "one sentence, playful",
+    "speaking_style": "short phrase",
+    "tools": ["subset of: change_lighting, consult_stage_oracle, inspect_prop"]
+  },
+  "puppet_actors": [
+    {
+      "name": "...",
+      "avatar": "emoji",
+      "avatar_image_url": "https or empty",
+      "goal": "...",
+      "secret": "...",
+      "speaking_style": "...",
+      "tools": ["..."]
+    },
+    {
+      "name": "...",
+      "avatar": "emoji",
+      "avatar_image_url": "https or empty",
+      "goal": "...",
+      "secret": "...",
+      "speaking_style": "...",
+      "tools": ["..."]
+    }
+  ]
+}
+
+Rules:
+- director.tools must include change_lighting or consult_stage_oracle (at least one).
+- puppet_actors must have **at least two** entries (exactly two preferred). Never put the director inside puppet_actors; never add a third puppet there if you already have a top-level director. Extra puppets beyond two are ignored by the app.
+- Names must be unique across all three characters.
+- Keep every string field under 200 characters (backdrop_description may be up to ~320 characters).
+- backdrop_description: REQUIRED. Describe a **minimal** wide-stage photographic background for puppets: soft light, simple shapes or gentle gradients, lots of calm empty space in the **center** for characters, **low detail**, **no crowds or faces**, **no text or logos**, **no busy fine patterns**. Mood may echo the premise but stay restrained so puppets stay readable. Do not include URLs here.
+- avatar_image_url may be https://api.dicebear.com/7.x/avataaars/svg?seed=ENCODED_NAME or empty.
+
+Premise:
+"""
+
+SHOW_BIBLE_SYSTEM_MESSAGE = (
+    "You are generating show metadata for AI Puppet Theater. "
+    "Return only one valid JSON object. No markdown. No commentary."
+)
+
+BACKDROP_URL_SYSTEM_MESSAGE = (
+    "You return one valid JSON object for AI Puppet Theater: only the key backdrop_image_url. "
+    "No markdown. No commentary."
+)
+
+# Any backend that can run a one-shot text completion for casting (same family as actor engine).
+_LLM_CAST_BACKENDS = frozenset({"hf_api", "openbmb", "local_lora", "local_gguf"})
+
+
+def llm_backend_order(director_mode: str, backend_name: str) -> list[str]:
+    """Prefer director LLM first, then actor backend, deduplicated."""
+    order: list[str] = []
+    for mode in (director_mode, backend_name):
+        key = (mode or "").strip().lower()
+        if key in _LLM_CAST_BACKENDS and key not in order:
+            order.append(key)
+    return order
+
+
+# Image hosts where we upgrade http→https so model output still counts as LLM backdrop.
+_HTTP_TO_HTTPS_IMAGE_HOSTS = frozenset(
+    {
+        "images.unsplash.com",
+        "plus.unsplash.com",
+        "cdn.pixabay.com",
+        "upload.wikimedia.org",
+    }
+)
+
+
+def _netloc_host(netloc: str) -> str:
+    host = netloc.split("@")[-1]
+    return host.split(":")[0].lower()
+
+
+def _strip_trailing_junk(url: str) -> str:
+    u = url.strip()
+    junk = ').,];}\'" \n\t'
+    while u and u[-1] in junk:
+        u = u[:-1]
+    return u
+
+
+def validate_https_url(raw: Any) -> str | None:
+    if raw is None:
+        return None
+    url = _strip_trailing_junk(str(raw).strip())
+    if not url:
+        return None
+    lower = url.lower()
+    if lower.startswith("http://"):
+        host = _netloc_host(urlparse(url).netloc)
+        if host in _HTTP_TO_HTTPS_IMAGE_HOSTS:
+            url = "https://" + url[7:]
+    parsed = urlparse(url)
+    if parsed.scheme != "https" or not parsed.netloc:
+        return None
+    if "@" in parsed.netloc:
+        return None
+    return url
+
+
+def _salvage_show_bible_backdrop_url(raw_text: str) -> str | None:
+    """
+    Recover a backdrop URL when the JSON field is missing/invalid but the model
+    still emitted a usable https image link in the completion.
+    """
+    patterns = (
+        r"https://images\.unsplash\.com/photo-[\w-]+(?:\?[\w%.&=+-]*)?",
+        r"https://plus\.unsplash\.com/premium_photo-[\w-]+(?:\?[\w%.&=+-]*)?",
+        r"https://cdn\.pixabay\.com/photo/[\w/.-]+(?:\?[\w%.&=+-]*)?",
+        r"https://upload\.wikimedia\.org/wikipedia/commons/[\w/.%-]+",
+    )
+    for pat in patterns:
+        m = re.search(pat, raw_text)
+        if m:
+            got = validate_https_url(m.group(0))
+            if got:
+                return got
+    return None
+
+
+def _extract_json_object(text: str) -> dict[str, Any] | None:
+    cleaned = text.strip()
+    fence = re.search(r"```(?:json)?\s*([\s\S]*?)\s*```", cleaned, re.IGNORECASE)
+    if fence:
+        cleaned = fence.group(1).strip()
+    start = cleaned.find("{")
+    end = cleaned.rfind("}")
+    if start == -1 or end <= start:
+        return None
+    try:
+        data = json.loads(cleaned[start : end + 1])
+    except json.JSONDecodeError:
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _filter_tools(raw: Any) -> list[str]:
+    if not isinstance(raw, list):
+        return []
+    out: list[str] = []
+    for item in raw:
+        name = str(item).strip()
+        if name in ALLOWED_TOOL_NAMES and name not in out:
+            out.append(name)
+    return out
+
+
+def _clip_avatar_emoji(s: str) -> str:
+    t = " ".join(s.strip().split())
+    if not t:
+        return "🎭"
+    return t[:16]
+
+
+def _actor_from_dict(blob: Any, default_tools: list[str]) -> Actor | None:
+    if not isinstance(blob, dict):
+        return None
+    name = " ".join(str(blob.get("name", "")).strip().split())
+    if not name:
+        return None
+    goal = " ".join(str(blob.get("goal", "")).strip().split()) or "Stay in character."
+    secret = " ".join(str(blob.get("secret", "")).strip().split()) or "Has a tiny backstage secret."
+    style = " ".join(str(blob.get("speaking_style", "")).strip().split()) or "playful and theatrical"
+    tools = _filter_tools(blob.get("tools"))
+    if not tools:
+        tools = list(default_tools)
+    avatar = _clip_avatar_emoji(str(blob.get("avatar", "🎭")))
+    img = validate_https_url(blob.get("avatar_image_url"))
+    return Actor(
+        name=name,
+        avatar=avatar,
+        goal=goal[:220],
+        secret=secret[:220],
+        speaking_style=style[:160],
+        tools=tools,
+        avatar_image_url=img,
+    )
+
+
+def build_backdrop_url_user_content(
+    premise: str,
+    show_title: str,
+    setting: str,
+    backdrop_description: str,
+) -> str:
+    prem = " ".join(premise.strip().split())[:900]
+    tit = " ".join(show_title.strip().split())[:120]
+    st = " ".join(setting.strip().split())[:400]
+    desc = " ".join(backdrop_description.strip().split())[:500]
+    return (
+        "Choose one real https image URL for a puppet stage backdrop (wide landscape).\n\n"
+        "Follow this art direction closely (minimal, readable behind puppets):\n"
+        f"{desc}\n\n"
+        "Context:\n"
+        f"- Premise: {prem}\n"
+        f"- Show title: {tit}\n"
+        f"- Setting (narrative): {st}\n\n"
+        "Rules for the image:\n"
+        "- https only; prefer images.unsplash.com or plus.unsplash.com; also allowed: cdn.pixabay.com, upload.wikimedia.org.\n"
+        "- Calm, uncluttered, generous empty space toward the center for puppets; no crowds, faces, signage, or busy textures.\n"
+        "- Return ONE JSON object only, no markdown, no extra keys:\n"
+        '  {"backdrop_image_url":"https://images.unsplash.com/photo-..."}\n'
+        "- Use a genuine URL pattern; prefer well-known generic landscape/studio/sky photos if unsure."
+    )
+
+
+def parse_backdrop_url_response(raw_text: str) -> str | None:
+    data = _extract_json_object(raw_text)
+    if data:
+        u = validate_https_url(data.get("backdrop_image_url"))
+        if u:
+            return u
+        for alt in ("backdrop_url", "background_image_url"):
+            u = validate_https_url(data.get(alt))
+            if u:
+                return u
+    return _salvage_show_bible_backdrop_url(raw_text)
+
+
+def resolve_backdrop_image_url_via_llm(
+    backend_name: str,
+    premise: str,
+    show_title: str,
+    setting: str,
+    backdrop_description: str,
+    *,
+    max_new_tokens: int | None = None,
+    temperature: float | None = None,
+) -> tuple[str | None, dict[str, object]]:
+    """
+    Second LLM step: turn minimal backdrop_description (+ premise/setting) into a validated image URL.
+    """
+    meta: dict[str, object] = {}
+    desc = " ".join(backdrop_description.strip().split())
+    if not desc:
+        desc = " ".join(setting.strip().split())
+        meta["description_fallback"] = "setting"
+    else:
+        meta["description_fallback"] = None
+    try:
+        raw = invoke_backdrop_image_url_llm(
+            backend_name,
+            premise=premise,
+            show_title=show_title,
+            setting=setting,
+            backdrop_description=desc,
+            max_new_tokens=max_new_tokens,
+            temperature=temperature,
+        )
+        meta["raw_char_len"] = len(raw)
+        meta["raw_preview"] = raw[:400]
+        url = parse_backdrop_url_response(raw)
+        meta["parsed_ok"] = bool(url)
+        return url, meta
+    except Exception as exc:
+        meta["error"] = str(exc)[:500]
+        return None, meta
+
+
+def parse_show_bible_response(raw_text: str) -> tuple[str, str, str | None, list[Actor]] | None:
+    data = _extract_json_object(raw_text)
+    if not data:
+        return None
+    title = " ".join(str(data.get("show_title", "")).strip().split())
+    setting = " ".join(str(data.get("setting", "")).strip().split())
+    if not title or not setting:
+        return None
+    raw_desc: Any = data.get("backdrop_description") or data.get("stage_backdrop_description")
+    backdrop_description = " ".join(str(raw_desc or "").strip().split()) or None
+    if backdrop_description and len(backdrop_description) > 360:
+        backdrop_description = backdrop_description[:360].rsplit(" ", 1)[0].rstrip(",;:") or backdrop_description[:360]
+    director_blob: Any
+    puppets: Any
+    raw_actors = data.get("actors")
+    if isinstance(raw_actors, list) and len(raw_actors) == 3 and all(isinstance(x, dict) for x in raw_actors):
+        director_blob = raw_actors[0]
+        puppets = raw_actors[1:3]
+    else:
+        director_blob = data.get("director")
+        puppets = data.get("puppet_actors")
+    if not isinstance(director_blob, dict) or not isinstance(puppets, list) or len(puppets) < 2:
+        return None
+    # Models often emit three puppets plus a separate director; we only stage director + two puppets.
+    if len(puppets) > 2:
+        puppets = puppets[:2]
+    director = _actor_from_dict(director_blob, ["change_lighting", "consult_stage_oracle"])
+    p0 = _actor_from_dict(puppets[0], ["consult_stage_oracle", "change_lighting"])
+    p1 = _actor_from_dict(puppets[1], ["inspect_prop", "change_lighting"])
+    if director is None or p0 is None or p1 is None:
+        return None
+    names = {director.name.lower(), p0.name.lower(), p1.name.lower()}
+    if len(names) != 3:
+        return None
+    actors = [director, p0, p1]
+    return title[:120], setting[:400], backdrop_description, actors
+
+
+def invoke_show_bible_llm(
+    backend_name: str,
+    premise: str,
+    *,
+    max_new_tokens: int | None = None,
+    temperature: float | None = None,
+    extra_user_suffix: str = "",
+) -> str:
+    """Run one completion; raises on failure."""
+    user_content = _SHOW_BIBLE_INSTRUCTIONS + premise.strip() + extra_user_suffix
+    budget = max_new_tokens if max_new_tokens is not None else 256
+    temp = float(temperature) if temperature is not None else 0.55
+
+    backend = get_backend(backend_name)
+    if isinstance(backend, HFAPIBackend):
+        return backend._generate_text(
+            user_content,
+            max_tokens=HF_API_SHOW_BIBLE_MAX_TOKENS,
+            temperature=0.35 if temperature is None else temp,
+        )
+
+    if isinstance(backend, OpenBMBTransformersBackend):
+        prev_tokens = backend.max_new_tokens
+        prev_temp = backend.temperature
+        ot = max(96, min(budget, 160))
+        backend.configure(max_new_tokens=ot, temperature=temp)
+        try:
+            return backend._generate_text(user_content)
+        finally:
+            backend.configure(max_new_tokens=prev_tokens, temperature=prev_temp)
+
+    if isinstance(backend, LocalLoRAActorBackend):
+        prev_tokens = backend.max_new_tokens
+        prev_temp = backend.temperature
+        mt = max(200, min(budget, 320))
+        backend.configure(max_new_tokens=mt, temperature=temp)
+        messages = [
+            {"role": "system", "content": SHOW_BIBLE_SYSTEM_MESSAGE},
+            {"role": "user", "content": user_content},
+        ]
+        try:
+            backend._load()
+            return _run_with_timeout(
+                lambda: backend._generate_text(messages),
+                backend.timeout_seconds,
+                "Local LoRA show bible generation timed out",
+            )
+        finally:
+            backend.configure(max_new_tokens=prev_tokens, temperature=prev_temp)
+
+    if isinstance(backend, LocalGGUFActorBackend):
+        prev_tokens = backend.max_new_tokens
+        prev_temp = backend.temperature
+        mt = max(200, min(budget, 320))
+        backend.configure(max_new_tokens=mt, temperature=temp)
+        messages = [
+            {"role": "system", "content": SHOW_BIBLE_SYSTEM_MESSAGE},
+            {"role": "user", "content": user_content},
+        ]
+        prompt = format_chatml(messages)
+        try:
+            backend._load()
+            return _run_with_timeout(
+                lambda: backend._generate_text(prompt),
+                backend.timeout_seconds,
+                "Local GGUF show bible generation timed out",
+            )
+        finally:
+            backend.configure(max_new_tokens=prev_tokens, temperature=prev_temp)
+
+    raise RuntimeError(f"Backend {backend_name!r} cannot run show bible LLM")
+
+
+def invoke_backdrop_image_url_llm(
+    backend_name: str,
+    *,
+    premise: str,
+    show_title: str,
+    setting: str,
+    backdrop_description: str,
+    max_new_tokens: int | None = None,
+    temperature: float | None = None,
+) -> str:
+    """One completion: JSON with backdrop_image_url only. Raises on failure."""
+    user_content = build_backdrop_url_user_content(premise, show_title, setting, backdrop_description)
+    budget = max_new_tokens if max_new_tokens is not None else 256
+    temp = float(temperature) if temperature is not None else 0.45
+
+    backend = get_backend(backend_name)
+
+    if isinstance(backend, HFAPIBackend):
+        return backend._generate_text(
+            user_content,
+            max_tokens=HF_API_BACKDROP_URL_MAX_TOKENS,
+            system_message=BACKDROP_URL_SYSTEM_MESSAGE,
+            temperature=0.25 if temperature is None else min(float(temp), 0.55),
+        )
+
+    if isinstance(backend, OpenBMBTransformersBackend):
+        prev_tokens = backend.max_new_tokens
+        prev_temp = backend.temperature
+        ot = max(64, min(budget, 140))
+        backend.configure(max_new_tokens=ot, temperature=min(temp, 0.45))
+        try:
+            return backend._generate_text(
+                f"{BACKDROP_URL_SYSTEM_MESSAGE}\n\n{user_content}",
+            )
+        finally:
+            backend.configure(max_new_tokens=prev_tokens, temperature=prev_temp)
+
+    if isinstance(backend, LocalLoRAActorBackend):
+        prev_tokens = backend.max_new_tokens
+        prev_temp = backend.temperature
+        mt = max(96, min(budget, 220))
+        backend.configure(max_new_tokens=mt, temperature=min(temp, 0.45))
+        messages = [
+            {"role": "system", "content": BACKDROP_URL_SYSTEM_MESSAGE},
+            {"role": "user", "content": user_content},
+        ]
+        try:
+            backend._load()
+            return _run_with_timeout(
+                lambda: backend._generate_text(messages),
+                backend.timeout_seconds,
+                "Local LoRA backdrop URL generation timed out",
+            )
+        finally:
+            backend.configure(max_new_tokens=prev_tokens, temperature=prev_temp)
+
+    if isinstance(backend, LocalGGUFActorBackend):
+        prev_tokens = backend.max_new_tokens
+        prev_temp = backend.temperature
+        mt = max(96, min(budget, 220))
+        backend.configure(max_new_tokens=mt, temperature=min(temp, 0.45))
+        messages = [
+            {"role": "system", "content": BACKDROP_URL_SYSTEM_MESSAGE},
+            {"role": "user", "content": user_content},
+        ]
+        prompt = format_chatml(messages)
+        try:
+            backend._load()
+            return _run_with_timeout(
+                lambda: backend._generate_text(prompt),
+                backend.timeout_seconds,
+                "Local GGUF backdrop URL generation timed out",
+            )
+        finally:
+            backend.configure(max_new_tokens=prev_tokens, temperature=prev_temp)
+
+    raise RuntimeError(f"Backend {backend_name!r} cannot run backdrop URL LLM")
+
+
+SUMMON_ACTOR_SYSTEM_MESSAGE = (
+    "You are casting one new puppet for AI Puppet Theater. "
+    "Return only one valid JSON object. No markdown. No commentary."
+)
+
+_SUMMON_ACTOR_SCHEMA = """
+Return ONE compact JSON object only. No markdown. Allowed top-level keys only:
+{
+  "name": "unique puppet stage name (must not match any name already on stage)",
+  "avatar": "single emoji",
+  "avatar_image_url": "https portrait URL or empty string",
+  "goal": "one sentence",
+  "secret": "one sentence, playful",
+  "speaking_style": "short phrase",
+  "tools": ["subset of: change_lighting, consult_stage_oracle, inspect_prop"]
+}
+
+Rules:
+- tools must be non-empty and only use allowed tool names.
+- name must be different from every name in "Names already on stage".
+- Incorporate the audience's suggested name or spirit, but you may refine it for the stage.
+- Keep every string field under 200 characters.
+- avatar_image_url may be https://api.dicebear.com/7.x/avataaars/svg?seed=ENCODED_NAME or empty.
+
+Show context:
+"""
+
+_SUMMON_REMINDER_SUFFIX = (
+    "\n\nReminder: respond with one JSON object only, keys "
+    "name, avatar, avatar_image_url, goal, secret, speaking_style, tools — no intent/line/emotion keys."
+)
+
+
+def build_summon_actor_user_content(session: TheaterSession, audience_suggested_name: str) -> str:
+    cast = ", ".join(a.name for a in session.actors) or "(none)"
+    label = audience_suggested_name.strip() or "Mystery Guest"
+    return (
+        f"{_SUMMON_ACTOR_SCHEMA}"
+        f"premise: {session.premise}\n"
+        f"show_title: {session.show_title}\n"
+        f"setting: {session.setting}\n"
+        f"Names already on stage: {cast}\n"
+        f"Audience asked to summon (suggested name): {label}\n"
+    )
+
+
+def parse_summoned_actor_response(raw_text: str) -> Actor | None:
+    data = _extract_json_object(raw_text)
+    if not data:
+        return None
+    blob: Any = data.get("summoned_actor")
+    if blob is None:
+        blob = data.get("actor")
+    if blob is None and isinstance(data.get("name"), str):
+        blob = data
+    if not isinstance(blob, dict):
+        return None
+    return _actor_from_dict(blob, ["consult_stage_oracle", "inspect_prop", "change_lighting"])
+
+
+def _unique_actor_name(actor: Actor, taken_lower: set[str], audience_label: str) -> Actor:
+    if actor.name.lower() not in taken_lower:
+        return actor
+    base = " ".join(audience_label.split()) or actor.name
+    for i in range(2, 14):
+        candidate = f"{base} {i}"
+        if candidate.lower() not in taken_lower:
+            return replace(actor, name=candidate)
+    return replace(actor, name=f"{base} the Wanderer")
+
+
+def invoke_summon_actor_llm(
+    backend_name: str,
+    user_content: str,
+    *,
+    max_new_tokens: int | None = None,
+    temperature: float | None = None,
+    extra_user_suffix: str = "",
+) -> str:
+    """One completion for summoned-actor JSON; raises on failure."""
+    text = user_content + extra_user_suffix
+    budget = max_new_tokens if max_new_tokens is not None else 256
+    temp = float(temperature) if temperature is not None else 0.55
+    backend = get_backend(backend_name)
+
+    if isinstance(backend, HFAPIBackend):
+        return backend._generate_text(
+            text,
+            max_tokens=HF_API_SUMMON_ACTOR_MAX_TOKENS,
+            temperature=0.35 if temperature is None else temp,
+        )
+
+    if isinstance(backend, OpenBMBTransformersBackend):
+        prev_tokens = backend.max_new_tokens
+        prev_temp = backend.temperature
+        ot = max(96, min(budget, 160))
+        backend.configure(max_new_tokens=ot, temperature=temp)
+        try:
+            return backend._generate_text(text)
+        finally:
+            backend.configure(max_new_tokens=prev_tokens, temperature=prev_temp)
+
+    if isinstance(backend, LocalLoRAActorBackend):
+        prev_tokens = backend.max_new_tokens
+        prev_temp = backend.temperature
+        mt = max(180, min(budget, 320))
+        backend.configure(max_new_tokens=mt, temperature=temp)
+        messages = [
+            {"role": "system", "content": SUMMON_ACTOR_SYSTEM_MESSAGE},
+            {"role": "user", "content": text},
+        ]
+        try:
+            backend._load()
+            return _run_with_timeout(
+                lambda: backend._generate_text(messages),
+                backend.timeout_seconds,
+                "Local LoRA summon actor generation timed out",
+            )
+        finally:
+            backend.configure(max_new_tokens=prev_tokens, temperature=prev_temp)
+
+    if isinstance(backend, LocalGGUFActorBackend):
+        prev_tokens = backend.max_new_tokens
+        prev_temp = backend.temperature
+        mt = max(180, min(budget, 320))
+        backend.configure(max_new_tokens=mt, temperature=temp)
+        messages = [
+            {"role": "system", "content": SUMMON_ACTOR_SYSTEM_MESSAGE},
+            {"role": "user", "content": text},
+        ]
+        prompt = format_chatml(messages)
+        try:
+            backend._load()
+            return _run_with_timeout(
+                lambda: backend._generate_text(prompt),
+                backend.timeout_seconds,
+                "Local GGUF summon actor generation timed out",
+            )
+        finally:
+            backend.configure(max_new_tokens=prev_tokens, temperature=prev_temp)
+
+    raise RuntimeError(f"Backend {backend_name!r} cannot run summon actor LLM")
+
+
+def resolve_summoned_actor_via_llm_or_default(
+    session: TheaterSession,
+    audience_suggested_name: str,
+) -> tuple[Actor, str | None, bool]:
+    """
+    Returns (actor, llm_backend_used_or_none, summon_llm_fallback_used).
+
+    summon_llm_fallback_used is True when an LLM backend was tried and parsing failed for all attempts.
+    """
+    label = " ".join(audience_suggested_name.strip().split()) or "Mystery Guest"
+    taken_lower = {a.name.lower() for a in session.actors}
+    default = Actor(
+        name=label,
+        avatar="✨",
+        goal="Make the scene stranger without derailing the finale.",
+        secret="Arrived with one completely unexplained cue.",
+        speaking_style="fresh, eager, and just a little too dramatic",
+        tools=["consult_stage_oracle"],
+    )
+
+    candidates = llm_backend_order(session.director_mode, session.backend_name)
+    if not candidates:
+        return default, None, False
+
+    user = build_summon_actor_user_content(session, label)
+    for mode in candidates:
+        suffixes: tuple[str, ...] = (
+            ("", _SUMMON_REMINDER_SUFFIX) if mode in {"local_lora", "local_gguf"} else ("",)
+        )
+        for suffix in suffixes:
+            try:
+                raw = invoke_summon_actor_llm(
+                    mode,
+                    user,
+                    max_new_tokens=session.backend_max_new_tokens,
+                    temperature=session.backend_temperature,
+                    extra_user_suffix=suffix,
+                )
+                actor = parse_summoned_actor_response(raw)
+                if actor is None:
+                    continue
+                actor = _unique_actor_name(actor, taken_lower, label)
+                if actor.name.lower() in taken_lower:
+                    continue
+                return actor, mode, False
+            except Exception:
+                continue
+
+    return default, None, True

puppet_theater/trace.py

@@ -9,6 +9,31 @@ from typing import Any
 
 from puppet_theater.models import TheaterSession
 
+"""
+Trace logging and export system for the AI Puppet Theater.
+
+This module is responsible for collecting, sanitizing, normalizing, and exporting
+runtime execution traces of a theater session.
+
+It captures all important system events such as:
+- Actor responses and intents
+- Director decisions
+- Tool usage (requests and results)
+- Audience interactions
+- Backend and validation metadata
+- Errors and fallback behavior
+
+Key responsibilities:
+1. Add structured trace events during a TheaterSession.
+2. Sanitize sensitive information (secrets, tokens, file paths).
+3. Normalize heterogeneous event formats into a consistent schema.
+4. Generate human-readable summaries for debugging and inspection.
+5. Export full session traces as JSON (in-memory or file-based).
+
+This module is primarily used for debugging, observability, and replay
+of AI-driven theater sessions.
+"""
+
 
 APP_NAME = "AI Puppet Theater"
 TRACE_VERSION = "1.0"
@@ -41,6 +66,15 @@ _PRIVATE_PATH_PATTERNS = [
 
 
 def add_trace_event(session: TheaterSession, event_type: str, **fields: Any) -> None:
+    """
+    Adds a structured event to the session trace log.
+
+    Automatically attaches metadata such as timestamp and step number,
+    and sanitizes all values before storing them in the session.
+
+    Used to record runtime events like actor responses, director decisions,
+    tool calls, and system actions.
+    """
     event: dict[str, Any] = {
         "event_type": sanitize_value(event_type),
         "type": sanitize_value(event_type),
@@ -56,6 +90,12 @@ def add_trace_event(session: TheaterSession, event_type: str, **fields: Any) ->
 
 
 def export_trace(session: TheaterSession | None) -> dict[str, Any] | None:
+    """
+    Builds a complete structured snapshot of the current theater session.
+
+    Includes session metadata, backend configuration, and all normalized
+    trace events in a consistent export format suitable for logging or analysis.
+    """
     if session is None:
         return None
 
@@ -86,6 +126,12 @@ def export_trace(session: TheaterSession | None) -> dict[str, Any] | None:
 
 
 def render_trace_json(session: TheaterSession | None) -> str:
+    """
+    Converts the exported trace into a pretty-printed JSON string.
+
+    Useful for debugging, logs, or displaying the full session state
+    in a human-readable format.
+    """
     payload = export_trace(session)
     if payload is None:
         return "No trace events yet."
@@ -93,6 +139,12 @@ def render_trace_json(session: TheaterSession | None) -> str:
 
 
 def write_trace_json_file(session: TheaterSession | None) -> str | None:
+    """
+    Writes the full trace export to a temporary JSON file.
+
+    The file is stored in the system temp directory and named using the
+    session ID. Used for downloading or offline inspection of traces.
+    """
     payload = export_trace(session)
     if payload is None:
         return None
@@ -107,6 +159,12 @@ def write_trace_json_file(session: TheaterSession | None) -> str | None:
 
 
 def normalize_trace_events(session: TheaterSession) -> list[dict[str, Any]]:
+    """
+    Converts raw trace events into a standardized format.
+
+    Handles both structured dict events and legacy string events,
+    ensuring all events conform to a consistent schema for downstream use.
+    """
     normalized: list[dict[str, Any]] = []
     for index, raw_event in enumerate(session.trace_events, start=1):
         if isinstance(raw_event, dict):
@@ -125,6 +183,12 @@ def normalize_trace_events(session: TheaterSession) -> list[dict[str, Any]]:
 
 
 def render_trace_summary(session: TheaterSession | None, max_events: int = 14) -> str:
+    """
+    Generates a human-readable summary of recent trace events.
+
+    Useful for quick debugging or UI display. Shows only the most recent
+    events with concise one-line explanations.
+    """
     if session is None:
         return "No trace events yet."
 
@@ -153,6 +217,13 @@ def render_trace_summary(session: TheaterSession | None, max_events: int = 14) -
 
 
 def _normalize_event_dict(raw_event: dict[str, Any], index: int) -> dict[str, Any]:
+    """
+    Normalizes a raw event dictionary into a structured trace format.
+
+    Extracts known fields, groups related metadata (director decisions,
+    tool usage, actor updates), and ensures output conforms to the
+    standard event schema.
+    """
     cleaned = {str(key): sanitize_value(value) for key, value in raw_event.items() if value is not None}
     event_type = str(cleaned.pop("event_type", cleaned.pop("type", "event")) or "event")
     normalized: dict[str, Any] = {
@@ -254,10 +325,22 @@ def _normalize_event_dict(raw_event: dict[str, Any], index: int) -> dict[str, An
 
 
 def _event_summary(event: dict[str, Any]) -> str:
+    """
+    Generates a short human-readable description of a trace event.
+
+    Used in summaries and logs to quickly understand what happened
+    without inspecting full event data.
+    """
     event_type = str(event.get("event_type") or "event")
     if event_type == "show_created":
         backend = _backend_label(event)
         return f"Show created with {backend}."
+    if event_type == "premise_cast_resolved":
+        title = event.get("resolved_show_title") or event.get("show_title") or "?"
+        source = event.get("premise_cast_source") or "?"
+        fb = event.get("cast_fallback_used")
+        n = len(event.get("cast_attempts") or []) if isinstance(event.get("cast_attempts"), list) else 0
+        return f"Premise cast: title={title!r} source={source} fallback={fb} attempts={n}."
     if event_type == "actors_created":
         return f"{event.get('actor_count', 'Actors')} actors created."
     if event_type == "director_decision":
@@ -298,6 +381,14 @@ def _event_summary(event: dict[str, Any]) -> str:
 
 
 def sanitize_value(value: Any) -> Any:
+    """
+    Recursively sanitizes values to remove sensitive or noisy information.
+
+    - Removes secrets, tokens, and credentials
+    - Redacts file paths
+    - Trims long strings
+    - Cleans nested structures (dicts, lists, tuples)
+    """
     if isinstance(value, dict):
         return {
             str(key): sanitize_value(item)
@@ -314,6 +405,18 @@ def sanitize_value(value: Any) -> Any:
 
 
 def _sanitize_text(value: str) -> str:
+    """
+    Cleans and redacts sensitive information from a string.
+
+    Removes:
+    - Extra whitespace
+    - Stack traces
+    - Environment secrets
+    - API keys and credentials
+    - Private file system paths
+
+    Also truncates long text for safe logging.
+    """
     text = " ".join(value.split())
     if "Traceback (most recent call last)" in text:
         text = "Error details redacted"
@@ -321,10 +424,6 @@ def _sanitize_text(value: str) -> str:
         if not _is_sensitive_key(key) or not secret:
             continue
         text = text.replace(secret, "[redacted]")
-    for secret_name in ("HF_TOKEN", "HUGGINGFACEHUB_API_TOKEN"):
-        secret = os.getenv(secret_name)
-        if secret:
-            text = text.replace(secret, "[redacted]")
     text = re.sub(
         r"\b([A-Z][A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|CREDENTIAL|API_KEY|ACCESS_KEY)[A-Z0-9_]*)\s*=\s*\S+",
         r"\1=[redacted]",
@@ -336,6 +435,12 @@ def _sanitize_text(value: str) -> str:
 
 
 def _backend_label(event: dict[str, Any]) -> str:
+    """
+    Builds a readable label for backend configuration.
+
+    Combines backend name and model ID (if available) to help identify
+    which model/engine produced an event.
+    """
     metadata = event.get("backend_metadata") if isinstance(event.get("backend_metadata"), dict) else {}
     backend = metadata.get("backend_name") or metadata.get("director_mode") or event.get("backend_name") or "backend"
     model = metadata.get("model_id") or event.get("model_id")
@@ -343,17 +448,37 @@ def _backend_label(event: dict[str, Any]) -> str:
 
 
 def _tool_label(tool_request: Any) -> str:
+    """
+    Extracts a readable tool name from a tool request structure.
+
+    Used in logs and summaries for tool-related events.
+    """
     if isinstance(tool_request, dict):
         return str(tool_request.get("tool_name") or "tool")
     return "tool"
 
 
 def _is_sensitive_key(key: str) -> bool:
+    """
+    Determines whether a key name contains sensitive information.
+
+    Used to prevent logging of secrets like:
+    - tokens
+    - passwords
+    - API keys
+    - credentials
+    """
     lowered = key.lower()
     return any(marker in lowered for marker in ("token", "secret", "password", "credential", "api_key", "access_key"))
 
 
 def _model_id_for_mode(mode: str | None) -> str | None:
+    """
+    Resolves model identifiers based on backend mode.
+
+    Maps execution modes (e.g., openbmb, hf_api) to their corresponding
+    model IDs for trace metadata.
+    """
     if mode == "openbmb":
         return os.getenv("OPENBMB_MODEL_ID", "openbmb/MiniCPM5-1B")
     if mode == "hf_api":

puppet_theater/zerogpu.py

@@ -1,9 +1,13 @@
 import os
+from pathlib import Path
 from typing import Callable, TypeVar
 
+from dotenv import load_dotenv
 
-F = TypeVar("F", bound=Callable)
 
+F = TypeVar("F", bound=Callable)
+# Repo root (parent of puppet_theater/), not cwd — matches app.py and tests.
+load_dotenv(Path(__file__).resolve().parent.parent / ".env")
 
 def _env_flag(name: str, default: bool = False) -> bool:
     value = os.getenv(name)
@@ -27,7 +31,7 @@ LAST_GPU_FALLBACK_REASON: str | None = (
     if USE_ZEROGPU and not SPACES_AVAILABLE
     else None
 )
-
+import torch
 
 def gpu_decorator(func: F) -> F:
     if not ZEROGPU_GPU_ACTIVE or spaces is None:

pyproject.toml

@@ -12,6 +12,7 @@ dependencies = [
     "peft==0.19.1",
     "pydantic<=2.12.5",
     "spaces==0.50.4",
+    "python-dotenv>=1.2.2",
     "torch==2.8.0",
     "transformers==5.10.2",
 ]

tests/test_director.py

@@ -32,11 +32,12 @@ def test_director_prompt_includes_audience_context_and_schema() -> None:
 
     prompt = build_director_prompt(session)
 
-    assert "The Moon Detective Interrogates Suspicious" in prompt
+    assert session.show_title in prompt
+    assert "A moon detective interrogates a suspicious toaster" in prompt
     assert "tiny crown" in prompt
     assert "Audience summoned Professor Button." in prompt
     assert "Professor Button" in prompt
-    assert "Has already misplaced the final cue card." in prompt
+    assert any(actor.secret in prompt for actor in session.actors)
     assert "Minimum beats before normal ending: 7" in prompt
     assert "Target beats: 10" in prompt
     assert "Maximum beats: 12" in prompt

tests/test_show_bible_parse.py

@@ -0,0 +1,62 @@
+"""Regression: show bible JSON shape variants from real models."""
+
+from puppet_theater.show_bible import parse_show_bible_response
+
+
+def test_parse_accepts_three_puppet_actors_plus_director() -> None:
+    """HF often returns director + three puppet_actors; we keep director + first two puppets."""
+    raw = """
+{
+  "show_title": "Benny's Birthday Bash",
+  "setting": "A sunny meadow with soft grass.",
+  "backdrop_description": "Soft sky, open center.",
+  "director": {
+    "name": "Puppet Master Pippa",
+    "avatar": "🎭",
+    "avatar_image_url": "",
+    "goal": "Guide the scene.",
+    "secret": "Secret one.",
+    "speaking_style": "Whimsical",
+    "tools": ["consult_stage_oracle", "change_lighting"]
+  },
+  "puppet_actors": [
+    {
+      "name": "Benny",
+      "avatar": "🧸",
+      "avatar_image_url": "",
+      "goal": "Find cake.",
+      "secret": "Secret two.",
+      "speaking_style": "Hopeful",
+      "tools": ["change_lighting"]
+    },
+    {
+      "name": "Rabbit Rosie",
+      "avatar": "🐰",
+      "avatar_image_url": "",
+      "goal": "Help Benny.",
+      "secret": "Secret three.",
+      "speaking_style": "Bouncy",
+      "tools": ["consult_stage_oracle"]
+    },
+    {
+      "name": "Turtle Tim",
+      "avatar": "🐢",
+      "avatar_image_url": "",
+      "goal": "Slow wisdom.",
+      "secret": "Secret four.",
+      "speaking_style": "Calm",
+      "tools": ["inspect_prop"]
+    }
+  ]
+}
+"""
+    out = parse_show_bible_response(raw)
+    assert out is not None
+    title, setting, desc, actors = out
+    assert title == "Benny's Birthday Bash"
+    assert "meadow" in setting.lower()
+    assert desc and "center" in desc.lower()
+    assert len(actors) == 3
+    assert actors[0].name == "Puppet Master Pippa"
+    assert actors[1].name == "Benny"
+    assert actors[2].name == "Rabbit Rosie"

uv.lock

@@ -38,6 +38,7 @@ dependencies = [
     { name = "huggingface-hub" },
     { name = "peft" },
     { name = "pydantic" },
+    { name = "python-dotenv" },
     { name = "spaces" },
     { name = "torch" },
     { name = "transformers" },
@@ -58,6 +59,7 @@ requires-dist = [
     { name = "peft", specifier = "==0.19.1" },
     { name = "pydantic", specifier = "<=2.12.5" },
     { name = "spaces", specifier = "==0.50.4" },
+    { name = "python-dotenv", specifier = ">=1.2.2" },
     { name = "torch", specifier = "==2.8.0" },
     { name = "transformers", specifier = "==5.10.2" },
 ]
@@ -1260,6 +1262,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/ec/57/56b9bcc3c9c6a792fcbaf139543cee77261f3651ca9da0c93f5c1221264b/python_dateutil-2.9.0.post0-py2.py3-none-any.whl", hash = "sha256:a8b2bc7bffae282281c8140a97d3aa9c14da0b136dfe83f850eea9a5f7470427", size = 229892, upload-time = "2024-03-01T18:36:18.57Z" },
 ]
 
+[[package]]
+name = "python-dotenv"
+version = "1.2.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/82/ed/0301aeeac3e5353ef3d94b6ec08bbcabd04a72018415dcb29e588514bba8/python_dotenv-1.2.2.tar.gz", hash = "sha256:2c371a91fbd7ba082c2c1dc1f8bf89ca22564a087c2c287cd9b662adde799cf3", size = 50135, upload-time = "2026-03-01T16:00:26.196Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/0b/d7/1959b9648791274998a9c3526f6d0ec8fd2233e4d4acce81bbae76b44b2a/python_dotenv-1.2.2-py3-none-any.whl", hash = "sha256:1d8214789a24de455a8b8bd8ae6fe3c6b69a5e3d64aa8a8e5d68e694bbcb285a", size = 22101, upload-time = "2026-03-01T16:00:25.09Z" },
+]
+
 [[package]]
 name = "python-multipart"
 version = "0.0.32"