From b7604167d828e2c6039b31328c849e4940039b22 Mon Sep 17 00:00:00 2001 From: CREDO23 Date: Wed, 10 Jun 2026 20:51:59 +0200 Subject: [PATCH] docs(podcasts): tighten comments and docstrings --- surfsense_backend/app/podcasts/__init__.py | 7 +++---- surfsense_backend/app/podcasts/api/__init__.py | 7 +------ surfsense_backend/app/podcasts/generation/__init__.py | 7 +++---- surfsense_backend/app/podcasts/generation/structured.py | 7 +++---- surfsense_backend/app/podcasts/tasks/draft.py | 7 +++---- surfsense_backend/app/podcasts/tts/adapters/litellm.py | 4 ++-- surfsense_backend/app/podcasts/voices/__init__.py | 5 ++--- surfsense_backend/app/podcasts/voices/catalog.py | 8 ++++---- 8 files changed, 21 insertions(+), 31 deletions(-) diff --git a/surfsense_backend/app/podcasts/__init__.py b/surfsense_backend/app/podcasts/__init__.py index 058274b4f..6a152af22 100644 --- a/surfsense_backend/app/podcasts/__init__.py +++ b/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 -``podcasts`` table model, which :mod:`app.db` re-exports so existing -``from app.db import Podcast`` call sites keep working during the migration. +Owns the ``podcasts`` table model, which :mod:`app.db` re-exports so existing +``from app.db import Podcast`` imports keep resolving. """ from __future__ import annotations diff --git a/surfsense_backend/app/podcasts/api/__init__.py b/surfsense_backend/app/podcasts/api/__init__.py index f943faeeb..4b5b12971 100644 --- a/surfsense_backend/app/podcasts/api/__init__.py +++ b/surfsense_backend/app/podcasts/api/__init__.py @@ -1,9 +1,4 @@ -"""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. -""" +"""HTTP API for the podcast lifecycle.""" from __future__ import annotations diff --git a/surfsense_backend/app/podcasts/generation/__init__.py b/surfsense_backend/app/podcasts/generation/__init__.py index 30a2425b0..a30b8f9af 100644 --- a/surfsense_backend/app/podcasts/generation/__init__.py +++ b/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 -(language detection + resolution), and ``transcript`` drafts long-form dialogue -outline-first. Everything else in the podcast pipeline is deterministic. +``brief`` proposes a reviewable spec from deterministic defaults; ``transcript`` +is the LLM-driven step, drafting long-form dialogue outline-first. """ from __future__ import annotations diff --git a/surfsense_backend/app/podcasts/generation/structured.py b/surfsense_backend/app/podcasts/generation/structured.py index 9e9731c2f..bcc03a6c7 100644 --- a/surfsense_backend/app/podcasts/generation/structured.py +++ b/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. -This mirrors the legacy podcaster's resilient parsing — strip fences, then fall -back to the outermost ``{...}`` span — so every generation node validates the -reply the same way instead of repeating ad-hoc parsing. +Agent LLMs return JSON wrapped in prose, markdown fences, or reasoning blocks, +so a plain ``model_validate_json`` is unreliable. Centralising the tolerant +parse here keeps every generation node validating replies the same way. """ from __future__ import annotations diff --git a/surfsense_backend/app/podcasts/tasks/draft.py b/surfsense_backend/app/podcasts/tasks/draft.py index 8d461bf9b..575daf2ba 100644 --- a/surfsense_backend/app/podcasts/tasks/draft.py +++ b/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 legacy generator. The API has already moved the row to DRAFTING and stored -the approved brief; this task drafts the long-form transcript and opens the -go/no-go gate. +The expensive, LLM-heavy step, so it runs under ``billable_call``. The API has +already moved the row to DRAFTING and stored the approved brief; this task +drafts the long-form transcript and opens the go/no-go gate. """ from __future__ import annotations diff --git a/surfsense_backend/app/podcasts/tts/adapters/litellm.py b/surfsense_backend/app/podcasts/tts/adapters/litellm.py index 55f49bd1e..181973b47 100644 --- a/surfsense_backend/app/podcasts/tts/adapters/litellm.py +++ b/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 -# under this, and retries cover transient upstream failures. +# A long single segment still finishes well under this; retries absorb transient +# upstream failures without failing the whole render. _TIMEOUT_SECONDS = 600 _MAX_RETRIES = 2 diff --git a/surfsense_backend/app/podcasts/voices/__init__.py b/surfsense_backend/app/podcasts/voices/__init__.py index 230b0b540..99560ab35 100644 --- a/surfsense_backend/app/podcasts/voices/__init__.py +++ b/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 -catalog via :func:`get_voice_catalog` and identify the configured provider via -:func:`provider_from_service`. +Callers obtain the catalog via :func:`get_voice_catalog` and identify the +configured provider via :func:`provider_from_service`. """ from __future__ import annotations diff --git a/surfsense_backend/app/podcasts/voices/catalog.py b/surfsense_backend/app/podcasts/voices/catalog.py index 591812943..28914e742 100644 --- a/surfsense_backend/app/podcasts/voices/catalog.py +++ b/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, -replacing the hardcoded speaker-id maps. Resolution uses it to pick defaults -for a brief, the API exposes it as picker options, and the renderer uses it to -turn a stored ``voice_id`` back into the provider-native reference. +A :class:`VoiceCatalog` is the single source of truth for which voices exist. +Resolution uses it to pick defaults for a brief, the API exposes it as picker +options, and the renderer uses it to turn a stored ``voice_id`` back into the +provider-native reference. """ from __future__ import annotations