docs(podcasts): tighten comments and docstrings

surfsense_backend/app/podcasts/__init__.py

@@ -1,8 +1,7 @@
-"""Podcast generation: brief resolution, transcript drafting, and audio rendering.
+"""Podcast feature: brief resolution, transcript drafting, and audio rendering.
 
-The public surface grows as the module is built. For now it owns the
+Owns the ``podcasts`` table model, which :mod:`app.db` re-exports so existing
-``podcasts`` table model, which :mod:`app.db` re-exports so existing
+``from app.db import Podcast`` imports keep resolving.
-``from app.db import Podcast`` call sites keep working during the migration.
 """
 
 from __future__ import annotations

surfsense_backend/app/podcasts/api/__init__.py

@@ -1,9 +1,4 @@
-"""HTTP API for the podcast lifecycle.
+"""HTTP API for the podcast lifecycle."""
-
-The router is mounted at cutover (replacing the legacy podcast routes); it is
-kept separate here so it can be wired in one step without colliding with the old
-routes during parallel development.
-"""
 
 from __future__ import annotations
 

surfsense_backend/app/podcasts/generation/__init__.py

@@ -1,8 +1,7 @@
-"""Generation: the LLM-driven brief and transcript controlled graphs.
+"""Generation: the controlled graphs that produce a brief and a transcript.
 
-Two small graphs hold all the intelligence: ``brief`` proposes a reviewable spec
+``brief`` proposes a reviewable spec from deterministic defaults; ``transcript``
-(language detection + resolution), and ``transcript`` drafts long-form dialogue
+is the LLM-driven step, drafting long-form dialogue outline-first.
-outline-first. Everything else in the podcast pipeline is deterministic.
 """
 
 from __future__ import annotations

surfsense_backend/app/podcasts/generation/structured.py

@@ -1,9 +1,8 @@
 """Parse a model's reply into a Pydantic shape, tolerating chatty output.
 
-Agent LLMs return JSON wrapped in prose, markdown fences, or reasoning blocks.
+Agent LLMs return JSON wrapped in prose, markdown fences, or reasoning blocks,
-This mirrors the legacy podcaster's resilient parsing — strip fences, then fall
+so a plain ``model_validate_json`` is unreliable. Centralising the tolerant
-back to the outermost ``{...}`` span — so every generation node validates the
+parse here keeps every generation node validating replies the same way.
-reply the same way instead of repeating ad-hoc parsing.
 """
 
 from __future__ import annotations

surfsense_backend/app/podcasts/tasks/draft.py

@@ -1,9 +1,8 @@
 """Transcript-drafting task: DRAFTING -> AWAITING_REVIEW.
 
-The expensive, LLM-heavy step, so it runs under ``billable_call`` exactly like
+The expensive, LLM-heavy step, so it runs under ``billable_call``. The API has
-the legacy generator. The API has already moved the row to DRAFTING and stored
+already moved the row to DRAFTING and stored the approved brief; this task
-the approved brief; this task drafts the long-form transcript and opens the
+drafts the long-form transcript and opens the go/no-go gate.
-go/no-go gate.
 """
 
 from __future__ import annotations

surfsense_backend/app/podcasts/tts/adapters/litellm.py

@@ -16,8 +16,8 @@ from ..request import SynthesisRequest
 # Hosted providers return MP3-encoded bytes from ``aspeech``.
 _CONTAINER = "mp3"
 
-# Matches the legacy podcaster timeouts; long single segments still finish well
+# A long single segment still finishes well under this; retries absorb transient
-# under this, and retries cover transient upstream failures.
+# upstream failures without failing the whole render.
 _TIMEOUT_SECONDS = 600
 _MAX_RETRIES = 2
 

surfsense_backend/app/podcasts/voices/__init__.py

@@ -1,8 +1,7 @@
 """Voices: the catalog of selectable TTS voices and the active provider.
 
-Replaces the legacy hardcoded speaker-id voice maps. Callers obtain the
+Callers obtain the catalog via :func:`get_voice_catalog` and identify the
-catalog via :func:`get_voice_catalog` and identify the configured provider via
+configured provider via :func:`provider_from_service`.
-:func:`provider_from_service`.
 """
 
 from __future__ import annotations

surfsense_backend/app/podcasts/voices/catalog.py

@@ -1,9 +1,9 @@
 """The voice catalog: look up and filter selectable voices.
 
-A :class:`VoiceCatalog` is the single source of truth for which voices exist,
+A :class:`VoiceCatalog` is the single source of truth for which voices exist.
-replacing the hardcoded speaker-id maps. Resolution uses it to pick defaults
+Resolution uses it to pick defaults for a brief, the API exposes it as picker
-for a brief, the API exposes it as picker options, and the renderer uses it to
+options, and the renderer uses it to turn a stored ``voice_id`` back into the
-turn a stored ``voice_id`` back into the provider-native reference.
+provider-native reference.
 """
 
 from __future__ import annotations