Add cascaded agent-framework init template; make all init templates importable + type-checked

.vscode/settings.json

@@ -0,0 +1,8 @@
+{
+  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+  "python.testing.pytestEnabled": true,
+  "python.testing.unittestEnabled": false,
+  "evenBetterToml.schema.enabled": false,
+  "mypy-type-checker.importStrategy": "fromEnvironment",
+  "mypy-type-checker.preferDaemon": true
+}

aai_cli/app/init_exec.py

@@ -61,7 +61,11 @@ def _pick_template() -> str:
     choice = questionary.select(
         "Pick a template",
         choices=[
-            questionary.Choice(title=templates.title_for(t), value=t)
+            questionary.Choice(
+                title=templates.title_for(t),
+                value=t,
+                description=templates.description_for(t),
+            )
             for t in templates.TEMPLATE_ORDER
         ],
     ).ask()
@@ -101,6 +105,10 @@ def _active_env_vars() -> dict[str, str]:
         "ASSEMBLYAI_STREAMING_HOST": env.streaming_host,
         # Voice Agent host mirrors the streaming host's naming across environments.
         "ASSEMBLYAI_AGENTS_HOST": env.streaming_host.replace("streaming", "agents", 1),
+        # Streaming-TTS host for the cascade (agent-framework) template. Empty in
+        # production, where streaming TTS has no host; that template then refuses to
+        # run and points at --sandbox.
+        "ASSEMBLYAI_TTS_HOST": env.streaming_tts_host,
     }
 
 

aai_cli/init/scaffold.py

@@ -39,7 +39,7 @@ def _template_root(template: str) -> Traversable:
         )
     # Navigate from the `aai_cli.init` package (templates/ has no __init__.py, so it
     # is not itself an importable package).
-    root = resources.files("aai_cli.init") / "templates" / template
+    root = resources.files("aai_cli.init") / "templates" / templates.dir_for(template)
     # Defense in depth: the registry should only list shipped templates, but if it ever
     # drifts ahead of the on-disk directories, fail cleanly instead of with a traceback.
     if not root.is_dir():
@@ -76,18 +76,25 @@ def existing_env_key(target: Path) -> str | None:
     return None
 
 
-def _copy_tree(node: Traversable, dest: Path) -> None:
+def _copy_tree(node: Traversable, dest: Path, *, top_level: bool = True) -> None:
     for child in node.iterdir():
         if child.name in _SKIP_NAMES or child.name.endswith(".pyc"):
             continue
+        # The template dir is an importable package in-repo (so it can be type-checked),
+        # but its root __init__.py is just that in-repo marker — not part of the shipped
+        # app. Skip it so the scaffolded project root doesn't become a stray package.
+        # (api/'s own __init__.py is one level down and IS copied — the shipped app's
+        # `from . import settings` needs it.)
+        if top_level and child.name == "__init__.py":
+            continue
         name = _DOTFILE_RENAMES.get(child.name, child.name)
         out = dest / name
         if child.is_dir():
             # parents=True is an equivalent mutant here: the walk always creates a
             # node's parent before descending, so `dest` (and `out.parent`) already
             # exists. exist_ok is exercised by the idempotent re-scaffold test.
             out.mkdir(parents=True, exist_ok=True)  # pragma: no mutate
-            _copy_tree(child, out)
+            _copy_tree(child, out, top_level=False)
         else:
             out.parent.mkdir(parents=True, exist_ok=True)  # pragma: no mutate
             out.write_bytes(child.read_bytes())

aai_cli/init/templates/__init__.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+# id -> human-facing title shown in the picker. Ids are Vercel-style
+# project/example slugs rather than CLI command names.
+#
+# Every id here MUST have a directory under templates/<id>/ (a test enforces both
+# directions) — the picker must never advertise a template that would crash on scaffold.
+TEMPLATES: dict[str, str] = {
+    "audio-transcription": "Audio Transcription",
+    "live-captions": "Live Captions",
+    "voice-agent": "Voice Agent",
+    "agent-framework": "Agent Framework",
+}
+
+# Display order for the picker and `--help`.
+TEMPLATE_ORDER: tuple[str, ...] = (
+    "audio-transcription",
+    "live-captions",
+    "voice-agent",
+    "agent-framework",
+)
+
+
+# One-line description shown beside each title in the interactive picker. Keys must
+# match TEMPLATES exactly (a test enforces both directions).
+DESCRIPTIONS: dict[str, str] = {
+    "audio-transcription": "Transcribe audio & video files, URLs, and YouTube — speaker labels and audio intelligence",
+    "live-captions": "Live real-time captions from your microphone over the Streaming API",
+    "voice-agent": "Full-duplex voice agent (speech in, LLM reply, speech out) via the Voice Agent API",
+    "agent-framework": "Cascaded voice agent you orchestrate: Streaming STT, the LLM Gateway, and sandbox TTS",
+}
+
+
+def dir_for(name: str) -> str:
+    """The on-disk template directory for an id: kebab id -> underscore package dir."""
+    return name.replace("-", "_")
+
+
+def is_template(name: str) -> bool:
+    return name in TEMPLATES
+
+
+def title_for(name: str) -> str:
+    """The human title for a template id, or the raw id if unknown."""
+    return TEMPLATES.get(name, name)
+
+
+def description_for(name: str) -> str:
+    """The one-line picker description for a template id, or '' when unknown."""
+    return DESCRIPTIONS.get(name, "")

aai_cli/init/templates/agent_framework/AGENTS.md

@@ -0,0 +1,37 @@
+# Agent Notes
+
+This is a buildless FastAPI + browser starter for a **cascaded** voice agent
+(Streaming STT -> LLM Gateway -> streaming TTS), orchestrated server-side. Run it with:
+
+```sh
+assembly dev
+```
+
+## Map
+
+- `api/settings.py`: API key, hosts, model, voice, system prompt, greeting, sample rates.
+- `api/cascade.py`: the orchestrator — STT/TTS socket helpers, the LLM stream, turn
+  detection, barge-in, and the `/ws` browser adapter. Built with injected `Deps` so it
+  is tested against fakes.
+- `api/index.py`: FastAPI app — serves the page/assets and the `/ws` WebSocket.
+- `static/app.js`: WebSocket lifecycle, mic capture, UI state, and event handling
+  (`_CONFIG` block at the top is the primary edit point).
+- `static/audio.js`: microphone pipeline, PCM conversion, playback queue, barge-in.
+- `static/styles.css`: visual styling only; the top `:root` block is the theme edit point.
+- `static/index.html`: page structure and static asset links.
+
+## Change Points
+
+- Model, voice, prompt, greeting, sample rates: edit `api/settings.py`.
+- Cascade behavior (turn detection, barge-in, LLM->TTS piping): edit `api/cascade.py`.
+- Transcript log rendering: edit `addTurn` in `static/app.js`.
+- Playback, barge-in, or PCM conversion: edit `static/audio.js`.
+
+## Invariants
+
+- Never expose `ASSEMBLYAI_API_KEY` or any server secret in `static/`.
+- Streaming TTS is sandbox-only; keep this app pointed at the sandbox hosts.
+- `reply.audio` carries base64 PCM on the `data` field.
+- The browser <-> backend event protocol matches the `voice-agent` template — keep it
+  stable so `static/audio.js` and the UI stay reusable.
+- Keep the app buildless unless the user explicitly asks for a frontend toolchain.

aai_cli/init/templates/agent_framework/README.md

@@ -0,0 +1,49 @@
+# Talk to a cascaded voice agent — AssemblyAI agent-framework starter
+
+Click connect and talk. Unlike the `voice-agent` template (which uses AssemblyAI's
+all-in-one Voice Agent API), this app is a **cascade your own backend orchestrates**:
+Streaming STT transcribes you, the LLM Gateway generates a reply, and streaming TTS
+speaks it back — with turn detection and barge-in handled server-side. The browser
+holds one WebSocket to your backend, so your API key never reaches the client.
+
+## Sandbox-only
+
+Streaming TTS has no production host, so the whole cascade runs against the AssemblyAI
+sandbox with a sandbox key. Scaffold it that way:
+
+```sh
+assembly --sandbox init agent-framework
+```
+
+That pins the sandbox hosts in `.env`. Running against production exits with a hint.
+
+## Run locally
+
+```sh
+assembly dev   # opens http://localhost:3000 (allow microphone access; headphones recommended)
+```
+
+`ASSEMBLYAI_API_KEY` is read from `.env` (created for you by `assembly init`).
+
+## Deploy
+
+This app keeps a **long-running WebSocket**, so it needs a persistent process — not
+Vercel's serverless functions. Use the shipped `Procfile`/`Dockerfile` on Render,
+Railway, Fly.io, or Google Cloud Run (`gcloud run deploy --source .`):
+
+```sh
+uvicorn api.index:app --host 0.0.0.0 --port $PORT
+```
+
+Set `ASSEMBLYAI_API_KEY` and the three sandbox host vars (`ASSEMBLYAI_STREAMING_HOST`,
+`ASSEMBLYAI_TTS_HOST`, `ASSEMBLYAI_LLM_GATEWAY_URL`) in the platform's environment.
+
+## Ideas to extend
+
+- Change the `MODEL`, `VOICE`, `SYSTEM_PROMPT`, `GREETING`, or `MAX_HISTORY` in
+  `api/settings.py`.
+- Replies already stream into TTS sentence-by-sentence as the LLM produces them
+  (`_generate_reply` flushes on each `.`/`!`/`?`), and a sliding window of
+  `MAX_HISTORY` messages gives the agent memory of the conversation. Tune the
+  sentence boundary or `MAX_HISTORY` to trade latency, cost, and recall.
+- Add tools (function calling) on the LLM leg so the agent can look things up.