vozonda 0.7.3__tar.gz

vozonda-0.7.3/.env.example

@@ -0,0 +1 @@
+VOZONDA_HF_HOME=/ai/models

vozonda-0.7.3/.gitignore

@@ -0,0 +1,24 @@
+node_modules/
+**/node_modules/
+dist/
+__pycache__/
+*.pyc
+.venv/
+**/.venv/
+data/
+*.db
+.DS_Store
+apps/web/public/demo/*.mp3
+
+# caches
+test-results/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.env
+*.env
+.aider*
+
+# Internal working docs live outside this repo (symlinked on the maintainer machine)
+docs/archive
+opencode.json

vozonda-0.7.3/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.5
+Name: vozonda
+Version: 0.7.3
+Summary: Vozonda orchestrator: url to two-voice podcast dialogue
+Requires-Python: >=3.11
+Requires-Dist: coincurve>=21.0.0
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.28
+Requires-Dist: lxml-html-clean>=0.4
+Requires-Dist: pillow>=10
+Requires-Dist: pydantic>=2.10
+Requires-Dist: readability-lxml>=0.8.4.1
+Requires-Dist: uvicorn[standard]>=0.34
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.9; extra == 'mcp'
+Provides-Extra: stt
+Requires-Dist: av<19,>=11; extra == 'stt'
+Requires-Dist: faster-whisper>=1.1; extra == 'stt'
+Provides-Extra: tts
+Requires-Dist: av<19,>=11; extra == 'tts'
+Requires-Dist: faster-whisper>=1.1; extra == 'tts'
+Requires-Dist: kokoro-onnx>=0.4; extra == 'tts'
+Requires-Dist: numpy>=1.26; extra == 'tts'
+Requires-Dist: numpy>=1.26.0; extra == 'tts'
+Requires-Dist: piper-tts>=1.2.0; extra == 'tts'
+Requires-Dist: qwen-tts>=0.1.0; extra == 'tts'
+Requires-Dist: soundfile>=0.12; extra == 'tts'
+Requires-Dist: soundfile>=0.12.0; extra == 'tts'
+Requires-Dist: torch>=2.2.0; extra == 'tts'
+Provides-Extra: tts-kokoro
+Requires-Dist: kokoro-onnx>=0.4; extra == 'tts-kokoro'
+Requires-Dist: numpy>=1.26; extra == 'tts-kokoro'
+Requires-Dist: soundfile>=0.12; extra == 'tts-kokoro'
+Provides-Extra: tts-piper
+Requires-Dist: piper-tts>=1.2.0; extra == 'tts-piper'
+Provides-Extra: tts-qwen
+Requires-Dist: numpy>=1.26.0; extra == 'tts-qwen'
+Requires-Dist: qwen-tts>=0.1.0; extra == 'tts-qwen'
+Requires-Dist: soundfile>=0.12.0; extra == 'tts-qwen'
+Requires-Dist: torch>=2.2.0; extra == 'tts-qwen'

vozonda-0.7.3/pyproject.toml

@@ -0,0 +1,78 @@
+[project]
+name = "vozonda"
+version = "0.7.3"
+description = "Vozonda orchestrator: url to two-voice podcast dialogue"
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.115",
+    "uvicorn[standard]>=0.34",
+    "httpx>=0.28",
+    "pydantic>=2.10",
+    "readability-lxml>=0.8.4.1",
+    "lxml_html_clean>=0.4",
+    "coincurve>=21.0.0",
+    "pillow>=10",
+]
+
+[project.optional-dependencies]
+tts-qwen = [
+    "torch>=2.2.0",
+    "soundfile>=0.12.0",
+    "numpy>=1.26.0",
+    "qwen-tts>=0.1.0",
+]
+tts-piper = [
+    "piper-tts>=1.2.0",
+]
+tts-kokoro = [
+    "kokoro-onnx>=0.4",
+    "soundfile>=0.12",
+    "numpy>=1.26",
+]
+# speech to text for audio sources (tray: audio files and podcast episodes)
+stt = [
+    "faster-whisper>=1.1",
+    # faster-whisper 1.2.1 calls av.open(metadata_errors=...), which PyAV 19 removed
+    "av>=11,<19",
+]
+tts = ["vozonda[tts-qwen]", "vozonda[tts-piper]", "vozonda[tts-kokoro]", "vozonda[stt]"]
+mcp = [
+    "mcp>=1.9",
+]
+
+[tool.uv]
+package = true
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "mypy>=2.3.1",
+    "pytest>=9.1.1",
+    "pytest-asyncio>=0.24.0",
+    "pytest-xdist>=3.5.0",
+    "ruff>=0.16.4",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vozonda_api"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+filterwarnings = [
+    "ignore:.*starlette\\.testclient.*",
+    "ignore:.*httpx.*",
+    "ignore::DeprecationWarning",
+]
+
+[project.scripts]
+vozonda = "vozonda_api.main:serve"
+vozonda-api = "vozonda_api.main:serve"
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+ignore = ["BLE001", "S112", "S110"]

vozonda-0.7.3/src/vozonda_api/__init__.py

@@ -0,0 +1,5 @@
+"""Vozonda API package."""
+
+from .version import BASE_VERSION, DISPLAY_VERSION, GIT_REV, __version__, get_version_info
+
+__all__ = ["BASE_VERSION", "DISPLAY_VERSION", "GIT_REV", "__version__", "get_version_info"]

vozonda-0.7.3/src/vozonda_api/access.py

@@ -0,0 +1,178 @@
+"""Who may read and write what once Vozonda is reachable from outside the host.
+
+Local use (the default: the API and the web UI published on 127.0.0.1 only) stays open, exactly as before:
+nobody else can reach it. A request counts as *remote* when
+
+- the install says it is exposed (VOZONDA_HOST is not a loopback address and the port is not published on
+  loopback only), or
+- it came through a reverse proxy: it carries X-Forwarded-For or Forwarded. A proxy in front of the web UI
+  (Caddy, nginx, Tailscale serve, a tunnel) adds them; the bundled web container and the Vite preview pass on
+  only what they received, plus the client address when it is not loopback, so a local browser sends none.
+  A client cannot make itself local by sending fewer headers than its proxy adds; or
+- it was addressed by a name other than a loopback one (Host header): a proxy that keeps the original host,
+  or the LAN and VPN address of the machine. VOZONDA_LOCAL_HOSTNAMES adds names that count as local.
+
+Remote requests are denied by default (GHSA-crq5-73gf-fv2h). They pass when
+
+- they carry the VOZONDA_TOKEN: as `Authorization: Bearer`, or as the session cookie the web UI gets once from
+  POST /auth/session (HttpOnly, SameSite=Strict), so the audio player and live updates work without headers;
+- the path is public by nature (health, voice probes, intro music, default artwork, the login itself);
+- the path is a feed (the feed checks its own key) or an episode's media or share page, and the request carries
+  the feed key (?key=, as the links in a private feed do) or the episode is public: its show's feed is public
+  or it was published to Nostr.
+
+Without a configured token, remote requests that need one get 503 with a hint, like writes always did.
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import re
+import sqlite3
+from contextvars import ContextVar
+
+from fastapi import Request
+
+from .env import env
+
+# Set per request by the access middleware in main.py, read by require_write_auth, so the many existing
+# require_write_auth(authorization) calls keep their signature.
+request_remote: ContextVar[bool] = ContextVar("vozonda_request_remote", default=False)
+request_authed: ContextVar[bool] = ContextVar("vozonda_request_authed", default=False)
+
+SESSION_COOKIE = "vozonda_session"
+SESSION_MAX_AGE = 30 * 24 * 3600
+_LOOPBACK_HOSTS = {"127.0.0.1", "::1", "localhost"}
+
+# Always public: nothing private behind them.
+_PUBLIC_EXACT = {"/health", "/og-default.png", "/img/og-default.png", "/llms.txt", "/styles/custom",
+                 "/auth/session", "/auth/nostr/challenge"}
+_PUBLIC_PREFIXES = ("/music/", "/audio/probe-")
+_FEED = re.compile(r"^/(?:feed\.xml|[^/]+/[^/]+/feed\.xml)$")
+# Paths that belong to one episode; group 1 is the file or id that starts with the job id.
+_EPISODE_PATHS = [
+    re.compile(r"^/audio/(.+)\.mp3$"),
+    re.compile(r"^/audio/(.+)\.peaks\.json$"),
+    re.compile(r"^/vtt/(.+)\.vtt$"),
+    re.compile(r"^/srt/(.+)\.srt$"),
+    re.compile(r"^/e/([^/]+)(?:/clip/.*)?$"),
+    re.compile(r"^/share/([^/]+)$"),
+    re.compile(r"^/source/([^/]+)$"),
+    re.compile(r"^/img/(.+)$"),
+]
+
+
+def install_exposed() -> bool:
+    """The install itself listens beyond loopback (or bills money): every request is remote."""
+    billing = env("ENABLE_BILLING", "false").strip().lower() == "true"
+    exposed = env("HOST", "127.0.0.1").strip() not in _LOOPBACK_HOSTS
+    if env("PUBLISHED_ON", "").strip().lower() == "loopback":
+        exposed = False
+    return billing or exposed
+
+
+def _host_name(host: str) -> str:
+    host = host.strip().lower()
+    if host.startswith("["):  # [::1]:8787
+        return host[1:host.find("]")] if "]" in host else host
+    return host.rsplit(":", 1)[0] if host.count(":") == 1 else host
+
+
+def is_remote(request: Request) -> bool:
+    if install_exposed():
+        return True
+    h = request.headers
+    if h.get("x-forwarded-for", "").strip() or h.get("forwarded", "").strip():
+        return True
+    host = _host_name(h.get("host", ""))
+    extra = {n.strip().lower() for n in env("LOCAL_HOSTNAMES", "").split(",") if n.strip()}
+    return bool(host) and host not in _LOOPBACK_HOSTS and host not in extra
+
+
+def token() -> str:
+    return env("TOKEN", "")
+
+
+def session_value(tok: str) -> str:
+    """Cookie value derived from the token: changing VOZONDA_TOKEN ends every session."""
+    return hmac.new(tok.encode(), b"vozonda-session-v1", hashlib.sha256).hexdigest()
+
+
+def is_authed(request: Request) -> bool:
+    tok = token()
+    if not tok:
+        return False
+    auth = request.headers.get("authorization") or ""
+    if hmac.compare_digest(auth.encode(), f"Bearer {tok}".encode()):
+        return True
+    cookie = request.cookies.get(SESSION_COOKIE) or ""
+    return bool(cookie) and hmac.compare_digest(cookie.encode(), session_value(tok).encode())
+
+
+def is_public_path(path: str) -> bool:
+    return path in _PUBLIC_EXACT or path.startswith(_PUBLIC_PREFIXES)
+
+
+def is_feed_path(path: str) -> bool:
+    return bool(_FEED.match(path))
+
+
+def episode_ref(path: str) -> str | None:
+    """The file or id an episode path names (its job id plus a suffix), or None if it is no episode path."""
+    for rx in _EPISODE_PATHS:
+        m = rx.match(path)
+        if m:
+            return m.group(1)
+    return None
+
+
+def _job_for_ref(ref: str) -> dict | None:
+    """The job a media name belongs to: the name itself, the part before -clip-, or a cover name's prefix."""
+    from .main import store
+
+    candidates = [ref, ref.split("-clip-")[0]]
+    stem = ref.rsplit(".", 1)[0]
+    candidates += [stem, stem.rsplit("-", 1)[0]]
+    for c in dict.fromkeys(candidates):
+        try:
+            return store.get(c)
+        except KeyError:
+            continue
+    return None
+
+
+def feed_key_ok(request: Request) -> bool:
+    from .settings_store import get_private_feed_key
+
+    key = request.query_params.get("key") or ""
+    return bool(key) and hmac.compare_digest(key.encode(), get_private_feed_key().encode())
+
+
+def job_is_public(job: dict) -> bool:
+    """Public when its show is public with RSS on (the feeds' rule, feeds._public_checker) or it was
+    published to Nostr."""
+    from .jobs import DB_PATH
+    from .routers.feeds import _public_checker
+
+    # the same rule as the feeds (feeds._job_show_num + _feed_is_public), so links and gate agree
+    if _public_checker()(job):
+        return True
+    try:
+        with sqlite3.connect(DB_PATH) as c:
+            row = c.execute("SELECT 1 FROM nostr_publish WHERE job_id = ? AND kind = 54 LIMIT 1",
+                            (job.get("id"),)).fetchone()
+        return row is not None
+    except sqlite3.Error:
+        return False
+
+
+def episode_media_allowed(request: Request, ref: str) -> bool:
+    if feed_key_ok(request):
+        return True
+    job = _job_for_ref(ref)
+    if job is None:
+        # watchlist show artwork is public; anything else unknown is not
+        return ref.startswith("watchlist-")
+    return job_is_public(job)
+
+

vozonda-0.7.3/src/vozonda_api/audio_source.py

@@ -0,0 +1,368 @@
+"""Audio transcription and punctuation restoration.
+
+Transcribes audio files (mp3, m4a, wav, ogg, opus) and podcast enclosures
+using faster-whisper, then restores punctuation with the local LLM punctuate
+pattern with word-for-word validation.
+
+Privacy: audio bytes are never written to disk in test paths; only the
+transcribed text is kept.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+import os
+import re
+import subprocess
+import sys
+import tempfile
+from typing import Any
+
+import httpx
+
+from .env import env
+
+logger = logging.getLogger(__name__)
+
+# Audio extensions that the source tray accepts.
+AUDIO_EXTS = (".mp3", ".m4a", ".wav", ".ogg", ".opus")
+# Maximum audio duration we will transcribe (seconds).
+MAX_AUDIO_DURATION_S = 3600  # 1 hour
+
+# Whisper model from env (default 'base').
+WHISPER_MODEL = env("WHISPER_MODEL", "base")
+
+# Punctuation chunk size (approximate words per chunk).
+PUNCTUATION_CHUNK_WORDS = 300
+# local servers (vLLM, Ollama) batch parallel requests; 4 keeps a small machine responsive
+PUNCTUATION_CONCURRENCY = int(env("PUNCTUATION_CONCURRENCY", "4"))
+
+
+def _words(text: str) -> list[str]:
+    return re.findall(r"[a-zA-Z0-9\u00c0-\u024f]+", text.lower())
+
+
+# ISO base media brands for M4A/AAC files.
+_ISO_AUDIO_BRANDS = (b"M4A ", b"M4B ", b"mp42", b"isom", b"dash")
+
+
+def detect_audio(data: bytes, ctype: str = "", ext: str = "") -> bool:
+    """Return True if the content looks like an audio file.
+
+    Recognised formats and their magic bytes::
+
+        MP3:  ID3v2 tag (b'ID3') or an MPEG audio frame sync (11 set bits)
+        WAV:  RIFF header with b'WAVE' at offset 8
+        Ogg:  page signature b'OggS' (Vorbis, Opus)
+        M4A:  ISO base media 'ftyp' box at offset 4, brand M4A , M4B , mp42, isom or dash at offset 8
+        FLAC: b'fLaC'
+
+    The ctype and ext arguments keep working as before: a content-type
+    starting with ``audio/`` or a matching extension returns True without
+    inspecting the bytes.
+    """
+    if ctype and any(ctype.startswith(p) for p in ("audio/",)):
+        return True
+    if ext and ext.lower() in AUDIO_EXTS:
+        return True
+    if not data:
+        return False
+    # ID3v2 tag (MP3 with metadata)
+    if data[:3] == b"ID3":
+        return True
+    # MPEG audio frame sync (bare MP3 stream)
+    if len(data) >= 2 and data[0] == 0xFF and (data[1] & 0xE0) == 0xE0:
+        return True
+    # WAV
+    if data[:4] == b"RIFF" and len(data) > 8 and data[8:12] == b"WAVE":
+        return True
+    # Ogg (Vorbis, Opus)
+    if data[:4] == b"OggS":
+        return True
+    # ISO base media file (M4A / AAC)
+    # the first 4 bytes are the box size, the box type follows at offset 4
+    if len(data) >= 12 and data[4:8] == b"ftyp" and data[8:12] in _ISO_AUDIO_BRANDS:
+        return True
+    # FLAC
+    return data[:4] == b"fLaC"
+
+
+async def transcribe_audio(
+    file_path: str | None = None,
+    file_bytes: bytes | None = None,
+) -> tuple[str, str, int, str | None]:
+    """Transcribe an audio file using faster-whisper.
+
+    Args:
+        file_path: Path to the audio file.
+        file_bytes: Raw audio bytes (file_path takes precedence).
+
+    Returns:
+        (title, text, duration_seconds, language) or raises SourceError.
+    """
+    from .sources import SourceError
+
+    tmp: tempfile.NamedTemporaryFile | None = None
+    actual_path: str = ""
+
+    try:
+        if file_bytes is not None:
+            tmp = tempfile.NamedTemporaryFile(  # noqa: SIM115
+                suffix=".audio", delete=False
+            )
+            tmp.write(file_bytes)
+            tmp.close()
+            actual_path = tmp.name
+        elif file_path:
+            actual_path = file_path
+        else:
+            raise SourceError("unreadable", "no audio data provided")
+
+        duration = _get_audio_duration(actual_path)
+        if duration > MAX_AUDIO_DURATION_S:
+            raise SourceError(
+                "too_large",
+                f"audio is {int(duration)}s (max {MAX_AUDIO_DURATION_S}s). "
+                "Split the file or provide a transcript.",
+            )
+
+        result = await asyncio.to_thread(_run_whisper_sync, actual_path, whisper_timeout(duration))
+        text = result.get("text", "").strip()
+        if not text:
+            raise SourceError("too_short", "the audio has no detectable speech")
+
+        lang = result.get("language")
+        title = f"Audio source ({int(duration)}s)"
+        return title, text, int(duration), lang
+
+    except SourceError:
+        raise
+    except Exception as exc:
+        raise SourceError("unreadable", f"transcription failed: {exc}") from exc
+    finally:
+        if tmp:
+            with contextlib.suppress(OSError):
+                os.unlink(actual_path)
+
+
+def _get_audio_duration(file_path: str) -> float:
+    """Get the duration of an audio file using ffprobe (if available).
+
+    Returns duration in seconds. Unknown duration is 0.
+    """
+    try:
+        res = subprocess.run(
+            [
+                "ffprobe",
+                "-v", "error",
+                "-show_entries", "format=duration",
+                "-of", "default=noprint_wrappers=1:nokey=1",
+                file_path,
+            ],
+            capture_output=True,
+            text=True,
+            timeout=10.0,
+            check=False,
+        )
+        if res.returncode == 0 and res.stdout.strip():
+            return float(res.stdout.strip())
+    except (subprocess.TimeoutExpired, FileNotFoundError, ValueError):
+        pass
+    return 0.0
+
+
+def whisper_timeout(duration_s: float) -> float:
+    """Seconds the Whisper subprocess may take: model load plus the audio at real time.
+
+    A fixed 300 s cut off long files on an ordinary CPU (an hour of audio with the base
+    model can take longer than five minutes). Unknown length gets the full one-hour budget.
+    """
+    length = duration_s if duration_s > 0 else MAX_AUDIO_DURATION_S
+    return max(300.0, 120.0 + length)
+
+
+def _run_whisper_sync(file_path: str, timeout: float = 300.0) -> dict[str, Any]:
+    """Run the Whisper transcription (synchronous).
+
+    Called via asyncio.to_thread from the async context.
+    In tests this is monkey-patched to avoid needing torch/faster-whisper.
+    """
+    import subprocess
+
+    from .sources import SourceError
+
+    try:
+        res = subprocess.run(
+            [
+                sys.executable,
+                "-c",
+                _WHISPER_SCRIPT_TEMPLATE,
+                file_path,
+                WHISPER_MODEL,
+            ],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+        )
+        if res.returncode != 0:
+            err = (res.stderr or "").strip()
+            raise SourceError("unreadable", f"transcription failed: {err}")
+        return json.loads(res.stdout)
+    except FileNotFoundError:
+        raise SourceError("unreadable", "whisper is not available")
+    except subprocess.TimeoutExpired:
+        raise SourceError("unreadable", f"transcription took longer than {int(timeout)} s")
+
+
+# Template for the inline Whisper script that runs in the renderer's venv.
+# The renderer venv has faster-whisper installed; the API venv may not.
+# The file path is passed as the first argument (sys.argv[1]).
+# The model name is passed as the second argument (sys.argv[2]).
+_WHISPER_SCRIPT_TEMPLATE = """\
+import json, sys, os
+try:
+    from faster_whisper import WhisperModel
+    model = WhisperModel(sys.argv[2], device="cpu", compute_type="int8")
+    # vad_filter skips silence: faster, and no invented text in quiet passages
+    segments, info = model.transcribe(sys.argv[1], language=None, vad_filter=True)
+    text = " ".join(s.text.strip() for s in segments).strip()
+    lang = info.language or "en"
+    print(json.dumps({"text": text, "language": lang}))
+except Exception as e:
+    print(json.dumps({"error": str(e)}))
+    sys.exit(1)
+"""
+
+
+async def restore_punctuation(text: str) -> tuple[str, bool]:
+    """Restore punctuation to raw whisper output with word-for-word validation.
+
+    Splits the text into chunks of about 300 words at word boundaries,
+    restores each chunk with its own request, and checks each chunk word
+    for word. A chunk that fails the check keeps its raw text; the others
+    keep their restored text. The result is the chunks joined with a space.
+
+    Each punctuation request sends "chat_template_kwargs": {"enable_thinking": false}
+    like the script provider and uses httpx.AsyncClient (no blocking call in the
+    event loop); max_tokens fits one chunk.
+
+    Args:
+        text: Raw transcribed text (may be unpunctuated).
+
+    Returns:
+        (punctuated_text, validated).
+    """
+    if not text or not text.strip():
+        return text, True
+
+    # Split original into words for chunking
+    words = re.findall(r"\S+", text)
+    if not words:
+        return text, True
+
+    # Split into chunks of ~PUNCTUATION_CHUNK_WORDS words at word boundaries
+    chunks: list[str] = []
+    for i in range(0, len(words), PUNCTUATION_CHUNK_WORDS):
+        chunk_words = words[i : i + PUNCTUATION_CHUNK_WORDS]
+        chunks.append(" ".join(chunk_words))
+
+    # Chunks run in parallel (PUNCTUATION_CONCURRENCY at a time); gather keeps their order.
+    sem = asyncio.Semaphore(PUNCTUATION_CONCURRENCY)
+
+    async def one(chunk: str) -> tuple[str, bool]:
+        original_words = _words(chunk)
+        if not original_words:
+            return chunk, True
+        try:
+            async with sem:
+                punctuated = await _llm_punctuate_async(chunk)
+        except Exception as exc:
+            logger.warning("punctuation restore failed for chunk: %s", exc, exc_info=True)
+            return chunk, False
+        # word for word: punctuation and capitals may change, the words and their order may not
+        if not punctuated or _words(punctuated) != original_words:
+            logger.debug("punctuation restore changed the words, keeping the raw chunk")
+            return chunk, False
+        return punctuated.strip(), True
+
+    results = await asyncio.gather(*(one(c) for c in chunks))
+    restored_chunks = [text for text, _ in results]
+    all_validated = all(ok for _, ok in results)
+
+    return " ".join(restored_chunks), all_validated
+
+
+async def _llm_punctuate_async(text: str) -> str:
+    """Send text to the local LLM for punctuation restoration (async).
+
+    Uses httpx.AsyncClient with chat_template_kwargs to disable thinking.
+    max_tokens is sized for a single chunk (~300 words).
+    """
+    from .providers import LLM_BASE, LLM_MODEL
+
+    prompt = (
+        "Restore punctuation and capitalization to the following text.\n"
+        "Do not add, remove, or reorder any words.\n"
+        "Output ONLY the punctuated text, nothing else.\n\n"
+        f"{text}"
+    )
+
+    # ~300 words * ~5 chars/word + prompt overhead = ~2000 tokens, use 4096 for safety
+    max_tokens = 4096
+
+    payload = {
+        "model": LLM_MODEL,
+        "messages": [{"role": "user", "content": prompt}],
+        "max_tokens": max_tokens,
+        "temperature": 0.0,
+        "chat_template_kwargs": {"enable_thinking": False},
+    }
+
+    async with httpx.AsyncClient(timeout=60.0) as client:
+        resp = await client.post(
+            f"{LLM_BASE.rstrip('/')}/chat/completions",
+            json=payload,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        result = data["choices"][0]["message"]["content"].strip()
+        if not result:
+            raise ValueError("punctuation model returned empty text")
+        return result
+
+
+# ---------------------------------------------------------------------------
+# Existing transcript extraction
+# ---------------------------------------------------------------------------
+
+# Regex patterns for podcast transcript tags.
+_PODCAST_TRANSCRIPT_RE = re.compile(
+    r"<podcast:transcript[^>]*>\s*(.*?)\s*</podcast:transcript>",
+    re.DOTALL,
+)
+
+
+def extract_existing_transcript(source_text: str | None) -> str | None:
+    """Extract an existing transcript from source text (RSS / podcast).
+
+    Some sources include a <podcast:transcript> tag with a pre-existing
+    transcript.  Extract and return it without re-transcribing.
+
+    Args:
+        source_text: The full source text to search.
+
+    Returns:
+        The extracted transcript text, or None if no transcript found.
+    """
+    if not source_text:
+        return None
+
+    match = _PODCAST_TRANSCRIPT_RE.search(source_text)
+    if match:
+        return match.group(1).strip()
+
+    return None