Merge pull request #466 from calesthio/codex/backlog-recovery-20260802

Recover bounded defects from the latest PR backlog

Author: calesthio

.env.example

@@ -2,72 +2,103 @@
 # Copy this to .env and fill in your keys
 
 # --- Image + video gateway ---
-FAL_KEY=                     # FLUX images, Google Veo video, Kling video, MiniMax video, Recraft images
-                             # Get one at https://fal.ai/dashboard/keys
-FAL_AI_API_KEY=              # Alias for FAL_KEY (some SDKs/docs use this name); either one is read.
+# FLUX images, Google Veo video, Kling video, MiniMax video, Recraft images.
+# Get one at https://fal.ai/dashboard/keys
+FAL_KEY=
+# Alias for FAL_KEY (some SDKs/docs use this name); either one is read.
+FAL_AI_API_KEY=
 
 # --- Replicate ---
-REPLICATE_API_TOKEN=         # Replicate-hosted video gen (seedance_replicate). Needed to make the
-                             # Replicate-backed Seedance path selectable alongside the fal.ai one.
-                             # Get one at https://replicate.com/account/api-tokens
+# Replicate-hosted video gen (seedance_replicate). Needed to make the
+# Replicate-backed Seedance path selectable alongside the fal.ai one.
+# Get one at https://replicate.com/account/api-tokens
+REPLICATE_API_TOKEN=
 
 # --- Higgsfield ---
-HIGGSFIELD_API_KEY=          # Higgsfield Cloud key (higgsfield_video). Pair with the secret below,
-HIGGSFIELD_API_SECRET=       # or use the combined HIGGSFIELD_KEY="<key>:<secret>" form instead.
+# Higgsfield Cloud key (higgsfield_video). Pair with the secret below,
+# or use the combined HIGGSFIELD_KEY="<key>:<secret>" form instead.
+HIGGSFIELD_API_KEY=
+HIGGSFIELD_API_SECRET=
 # HIGGSFIELD_KEY=            # Combined key:secret — set this INSTEAD of the _KEY/_SECRET pair if you prefer.
 
 # --- Kling official direct API ---
-KLING_API_KEY=               # Official Kling API key; enables video, image, TTS, avatar, lip sync
-KLING_API_BASE_URL=          # Optional endpoint override; leave blank for default https://api-singapore.klingai.com
-                             # Mainland China accounts can use https://api-beijing.klingai.com
+# Official Kling API key; enables video, image, TTS, avatar, lip sync.
+KLING_API_KEY=
+# Optional endpoint override; leave blank for default https://api-singapore.klingai.com
+# Mainland China accounts can use https://api-beijing.klingai.com
+KLING_API_BASE_URL=
 
 # --- Google (one key unlocks image gen + TTS + video) ---
-GOOGLE_API_KEY=              # Google Imagen images, Google Cloud TTS (700+ voices, 50+ languages),
-                             # Gemini Omni video (generation + conversational editing, paid tier)
-                             # Get one at https://aistudio.google.com/apikey
+# Google Imagen images, Google Cloud TTS (700+ voices, 50+ languages),
+# Gemini Omni video (generation + conversational editing, paid tier).
+# Get one at https://aistudio.google.com/apikey
+GOOGLE_API_KEY=
 # GEMINI_API_KEY=            # Alias for GOOGLE_API_KEY (takes precedence when both are set)
 # Alternative to the API key: service-account JSON auth.
 # TTS uses Cloud Text-to-Speech; Imagen routes to Vertex AI.
-GOOGLE_APPLICATION_CREDENTIALS=   # path to a service-account JSON key file
-GOOGLE_CLOUD_PROJECT=             # GCP project id (required for Imagen via Vertex AI)
-GOOGLE_CLOUD_LOCATION=            # Vertex AI region, default us-central1
+# Path to a service-account JSON key file.
+GOOGLE_APPLICATION_CREDENTIALS=
+# GCP project id (required for Imagen via Vertex AI).
+GOOGLE_CLOUD_PROJECT=
+# Vertex AI region, default us-central1.
+GOOGLE_CLOUD_LOCATION=
 
 # --- Voice ---
-ELEVENLABS_API_KEY=          # TTS narration, music generation, sound effects
-OPENAI_API_KEY=              # OpenAI TTS fallback and GPT Image 2 image generation
-XAI_API_KEY=                 # Grok image generation/editing and Grok video generation
-DOUBAO_SPEECH_API_KEY=       # Volcengine Doubao Speech TTS (new console API Key)
-DOUBAO_SPEECH_VOICE_TYPE=    # Default Doubao speaker/voice type, e.g. zh_female_vv_uranus_bigtts
+# TTS narration, music generation, sound effects.
+ELEVENLABS_API_KEY=
+# OpenAI TTS fallback and GPT Image 2 image generation.
+OPENAI_API_KEY=
+# Grok image generation/editing and Grok video generation.
+XAI_API_KEY=
+# Volcengine Doubao Speech TTS (new console API Key).
+DOUBAO_SPEECH_API_KEY=
+# Default Doubao speaker/voice type, e.g. zh_female_vv_uranus_bigtts.
+DOUBAO_SPEECH_VOICE_TYPE=
 # Piper local voices do not require env vars; install `piper-tts` via pip
 
 # --- DashScope (Alibaba Cloud Bailian) ---
-DASHSCOPE_API_KEY=           # Qwen image gen (qwen-image-2.0-pro), TTS (qwen3-tts-flash), ASR with word timestamps (qwen3-asr-flash-filetrans)
-                              # Get one at https://dashscope.aliyun.com/
+# Qwen image gen (qwen-image-2.0-pro), TTS (qwen3-tts-flash), ASR with word timestamps (qwen3-asr-flash-filetrans).
+# Get one at https://dashscope.aliyun.com/
+DASHSCOPE_API_KEY=
 
 # --- Music ---
-SUNO_API_KEY=                # Suno AI music generation (full songs, instrumentals, any genre)
+# Suno AI music generation (full songs, instrumentals, any genre).
+SUNO_API_KEY=
 
 # --- Video Generation ---
-HEYGEN_API_KEY=              # HeyGen API (VEO, Sora, Runway, Kling, Seedance via single key)
-RUNWAY_API_KEY=              # Runway Gen-4 (direct API, alternative to fal.ai routing)
-VOLC_ACCESSKEY=              # Volcengine Jimeng (即梦 AI) video generation via official API (HMAC-SHA256 V4 signing)
-VOLC_SECRETKEY=             # Secret Access Key paired with VOLC_ACCESSKEY. Get both at https://console.volcengine.com/iam/keymanage
-VIDEO_GEN_LOCAL_ENABLED=     # Set to "true" for local video gen (needs GPU + diffusers)
-VIDEO_GEN_LOCAL_MODEL=       # Local model: wan2.1-1.3b, wan2.1-14b, hunyuan-1.5, ltx2-local, cogvideo-5b
-MODAL_LTX2_ENDPOINT_URL=    # Modal self-hosted LTX-2 endpoint (optional)
+# HeyGen API (VEO, Sora, Runway, Kling, Seedance via single key).
+HEYGEN_API_KEY=
+# Runway Gen-4 (direct API, alternative to fal.ai routing).
+RUNWAY_API_KEY=
+# Volcengine Jimeng (即梦 AI) video generation via official API (HMAC-SHA256 V4 signing).
+VOLC_ACCESSKEY=
+# Secret Access Key paired with VOLC_ACCESSKEY. Get both at https://console.volcengine.com/iam/keymanage
+VOLC_SECRETKEY=
+# Set to "true" for local video gen (needs GPU + diffusers).
+VIDEO_GEN_LOCAL_ENABLED=
+# Local model: wan2.1-1.3b, wan2.1-14b, hunyuan-1.5, ltx2-local, cogvideo-5b.
+VIDEO_GEN_LOCAL_MODEL=
+# Modal self-hosted LTX-2 endpoint (optional).
+MODAL_LTX2_ENDPOINT_URL=
 
 # --- Stock Media ---
-PEXELS_API_KEY=              # Pexels stock footage/images (free)
-PIXABAY_API_KEY=             # Pixabay stock footage/images (free)
-UNSPLASH_ACCESS_KEY=         # Unsplash stock images (free developer key)
+# Pexels stock footage/images (free).
+PEXELS_API_KEY=
+# Pixabay stock footage/images (free).
+PIXABAY_API_KEY=
+# Unsplash stock images (free developer key).
+UNSPLASH_ACCESS_KEY=
 
 # --- Analysis ---
-HF_TOKEN=                    # HuggingFace token — enables speaker diarization in transcriber
+# HuggingFace token — enables speaker diarization in transcriber.
+HF_TOKEN=
 # Speech-to-text: optional Azure AI Speech (Fast Transcription). When set, the
 # agent prefers azure_stt for cloud STT; the local faster-whisper transcriber
 # remains the default offline path.
-AZURE_SPEECH_KEY=            # Azure AI Speech resource key ('Keys and Endpoint' page)
-AZURE_SPEECH_REGION=         # Speech resource region, e.g. eastus
+# Azure AI Speech resource key ('Keys and Endpoint' page).
+AZURE_SPEECH_KEY=
+# Speech resource region, e.g. eastus.
+AZURE_SPEECH_REGION=
 # AZURE_SPEECH_ENDPOINT=     # Optional: full custom endpoint URL (overrides region)
 
 # --- Avatar (local installs) ---

AGENT_GUIDE.md

@@ -528,9 +528,10 @@ Music is a critical part of any video. **Surface the music situation to the user
 
 Check music availability in this order and present the options:
 
-1. **User music library (`music_library/`):** Check if this folder exists and contains tracks. If so, list available tracks with durations and let the user pick one.
-2. **Music generation APIs:** Check which music tools are available via the registry (`registry.get_by_capability("music_generation")`). Report their status honestly — include quota status if known.
-3. **Royalty-free sources:** Note if the user can provide their own track (e.g., from YouTube Audio Library, Jamendo, or other free sources). Offer the `music_library/` drop path.
+1. **User music library:** Check `registry.get_by_capability("music_library")` and inspect `music_library/`. If tracks exist, list durations and let the user pick one.
+2. **Royalty-free search:** Check `registry.get_by_capability("music_search")` for configured search/download tools. Report licensing constraints and whether a key is required.
+3. **Music generation APIs:** Check `registry.get_by_capability("music_generation")`. Report status, quota, cost, and quality tradeoffs honestly.
+4. **Bring your own:** Note that the user can provide a track (for example from YouTube Audio Library or Jamendo) through the `music_library/` drop path.
 
 **Always present the user with explicit choices:**
 - Use a track from their library (which one?)

backlot/server.py

@@ -10,6 +10,7 @@
 import asyncio
 import json
 import time
+from contextlib import asynccontextmanager, suppress
 from pathlib import Path
 from typing import Optional
 
@@ -147,18 +148,22 @@ async def _watch_projects() -> None:
             hub.publish(pid)
 
 
-def create_app() -> FastAPI:
-    app = FastAPI(title="Backlot", docs_url=None, redoc_url=None)
+@asynccontextmanager
+async def _lifespan(app: FastAPI):
+    """Own and cleanly stop the project watcher with FastAPI's lifespan API."""
+
+    task = asyncio.create_task(_watch_projects())
+    app.state.watch_task = task
+    try:
+        yield
+    finally:
+        task.cancel()
+        with suppress(asyncio.CancelledError):
+            await task
 
-    @app.on_event("startup")
-    async def _startup() -> None:
-        app.state.watch_task = asyncio.create_task(_watch_projects())
 
-    @app.on_event("shutdown")
-    async def _shutdown() -> None:
-        task = getattr(app.state, "watch_task", None)
-        if task:
-            task.cancel()
+def create_app() -> FastAPI:
+    app = FastAPI(title="Backlot", docs_url=None, redoc_url=None, lifespan=_lifespan)
 
     # ---- API ----------------------------------------------------------
 

backlot/state.py

@@ -9,6 +9,7 @@
 
 import json
 import re
+from functools import lru_cache
 from pathlib import Path
 from typing import Any, Optional
 
@@ -59,6 +60,7 @@ def _rel(project_dir: Path, path: Path) -> str:
 # Pipeline / stages
 # ---------------------------------------------------------------------------
 
+@lru_cache(maxsize=32)
 def _load_pipeline_meta(pipeline_type: Optional[str]) -> dict[str, Any]:
     """Stage order + gate flags from the manifest; graceful fallback."""
     if pipeline_type and pipeline_type != "unknown":