Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

9.6 KB
Raw Blame
"""Base abstractions and shared helpers for voice providers."""

from __future__ import annotations

from abc import ABC, abstractmethod
import asyncio
from dataclasses import dataclass
import logging
import re

import httpx

from deeptutor.services.voice.config import (
    AUTH_API_KEY_HEADER,
    AUTH_TOKEN,
    STTConfig,
    TTSConfig,
)
from deeptutor.services.voice.speech_text import verbalize_latex_for_speech

logger = logging.getLogger(__name__)


class VoiceProviderError(RuntimeError):
    """Raised when a TTS/STT provider request fails or is misconfigured."""

    def __init__(self, message: str, *, public_message: str | None = None) -> None:
        super().__init__(message)
        # Only application-authored text belongs here, never an upstream body.
        self.public_message = public_message


class VoiceProviderTimeout(VoiceProviderError):
    """A synthesis deadline or transport timeout, with safe actionable copy."""

    def __init__(self) -> None:
        super().__init__(
            "Speech synthesis timed out. Increase Request timeout (seconds) in the speech "
            "model settings or try shorter text."
        )


class VoiceProviderHTTPError(VoiceProviderError):
    """Provider returned a non-2xx HTTP response."""

    def __init__(
        self,
        message: str,
        *,
        status_code: int,
        body: str = "",
        public_message: str | None = None,
    ) -> None:
        super().__init__(message, public_message=public_message)
        self.status_code = status_code
        self.body = body


class BaseTTSAdapter(ABC):
    """Abstract text-to-speech adapter."""

    @abstractmethod
    async def synthesize(self, text: str, config: TTSConfig) -> tuple[bytes, str]:
        """Synthesize ``text`` to audio.

        Returns:
            ``(audio_bytes, content_type)`` — content type is best-effort, e.g.
            ``audio/mpeg`` for mp3.
        """


async def synthesize_with_timeout(
    adapter: BaseTTSAdapter, text: str, config: TTSConfig
) -> tuple[bytes, str]:
    """One deadline covers synthesis, streams and audio downloads in every entry point."""
    try:
        async with asyncio.timeout(config.request_timeout):
            return await adapter.synthesize(text, config)
    except (TimeoutError, httpx.TimeoutException) as exc:
        raise VoiceProviderTimeout() from exc
    except VoiceProviderError as exc:
        # Existing adapters wrap transport errors. Preserve a timeout's identity
        # so the API can explain how to change the limit without echoing upstream data.
        if isinstance(exc.__cause__, (TimeoutError, httpx.TimeoutException)):
            raise VoiceProviderTimeout() from exc
        raise


@dataclass(frozen=True, slots=True)
class TranscriptCue:
    """One timed span of recognised speech, relative to the clip's own start.

    ``timed`` is False for providers that only return a transcript, so callers
    can tell "this whole clip says X" apart from "these words were said at
    01:12" instead of guessing from a zero start time.
    """

    start_seconds: float
    end_seconds: float
    text: str
    timed: bool = True


class BaseSTTAdapter(ABC):
    """Abstract speech-to-text adapter."""

    @abstractmethod
    async def transcribe(
        self,
        audio: bytes,
        config: STTConfig,
        *,
        filename: str = "audio.webm",
        content_type: str = "application/octet-stream",
    ) -> str:
        """Transcribe ``audio`` bytes to text."""

    async def transcribe_cues(
        self,
        audio: bytes,
        config: STTConfig,
        *,
        filename: str = "audio.webm",
        content_type: str = "application/octet-stream",
    ) -> list[TranscriptCue]:
        """Transcribe into timed cues, when the provider can produce them.

        The base implementation returns the plain transcript as one untimed
        cue, so a provider that cannot report word timings degrades to exactly
        today's behaviour instead of failing. Adapters that can do better
        override this.
        """
        text = await self.transcribe(audio, config, filename=filename, content_type=content_type)
        cleaned = (text or "").strip()
        return [TranscriptCue(0.0, 0.0, cleaned, timed=False)] if cleaned else []


def build_auth_headers(auth_style: str, api_key: str) -> dict[str, str]:
    """Map an ``auth_style`` + key onto request headers.

    ``bearer`` (default) → ``Authorization: Bearer``; ``api_key_header`` →
    ``api-key`` (Azure); ``token`` → ``Authorization: Token`` (Deepgram-style).
    """
    if not api_key:
        return {}
    if auth_style == AUTH_API_KEY_HEADER:
        return {"api-key": api_key}
    if auth_style == AUTH_TOKEN:
        return {"Authorization": f"Token {api_key}"}
    return {"Authorization": f"Bearer {api_key}"}


def normalize_stt_content_type(content_type: str | None) -> str:
    """Strip MIME parameters that STT APIs reject.

    Chrome's ``MediaRecorder.mimeType`` is typically ``audio/webm;codecs=opus``.
    OpenAI-compatible transcription endpoints treat the codec parameter as an
    unknown format and return 400 (``Unsupported file format: ...``). Keep the
    type/subtype only.
    """
    media_type = (content_type or "").split(";", 1)[0].strip()
    return media_type or "application/octet-stream"


def join_audio_path(base_url: str, suffix: str) -> str:
    """Append a speech API path to a configured base URL.

    ``base_url`` is the API base (e.g. ``https://api.openai.com/v1``). If the
    admin already pasted a full ``.../audio/...`` endpoint (some gateways /
    Azure deployments), it is used verbatim and the query string preserved.
    """
    base = (base_url or "").strip()
    if not base:
        raise VoiceProviderError("No endpoint URL configured for this provider.")
    head, sep, query = base.partition("?")
    if "/audio/" in head or head.rstrip("/").endswith("/" + suffix.strip("/")):
        return base
    joined = f"{head.rstrip('/')}/{suffix.lstrip('/')}"
    return f"{joined}?{query}" if sep else joined


# Content blocks that should never be spoken aloud, stripped before synthesis.
_FENCED_CODE = re.compile(r"```.*?```", re.DOTALL)
_INLINE_CODE = re.compile(r"`([^`]*)`")
_IMAGE = re.compile(r"!\[[^\]]*\]\([^)]*\)")
_LINK = re.compile(r"\[([^\]]+)\]\([^)]*\)")
_HEADING = re.compile(r"^\s{0,3}#{1,6}\s*", re.MULTILINE)
_BLOCKQUOTE = re.compile(r"^\s{0,3}>\s?", re.MULTILINE)
_LIST_MARKER = re.compile(r"^\s{0,3}(?:[-*+]|\d+[.)])\s+", re.MULTILINE)
_BOLD_STARS = re.compile(r"\*\*(.+?)\*\*", re.DOTALL)
_BOLD_UNDERS = re.compile(r"__(.+?)__", re.DOTALL)
_STRIKE = re.compile(r"~~(.+?)~~", re.DOTALL)
_ITALIC_STARS = re.compile(r"(?<!\*)\*(?!\*)(.+?)(?<!\*)\*(?!\*)", re.DOTALL)
_ITALIC_UNDERS = re.compile(r"(?<!\w)_(?!_)(.+?)(?<!_)_(?!\w)", re.DOTALL)
_HTML_TAG = re.compile(r"<[^>]+>")
_TABLE_PIPE = re.compile(r"^\s*\|.*\|\s*$", re.MULTILINE)
_WHITESPACE = re.compile(r"[ \t]+")
_BLANK_LINES = re.compile(r"\n{3,}")


def _unwrap_emphasis_for_speech(text: str) -> str:
    """Turn Markdown bold/italic/strike into plain words.

    Voice models otherwise speak ``*`` as "asterisk". Call this on verbalized
    math, or only on prose segments when math verbalization is disabled. Leftover unmatched ``**`` markers are dropped; a remaining
    single ``*`` is turned into a space so "asterisk" is never read.
    """
    out = _BOLD_STARS.sub(r"\1", text)
    out = _BOLD_UNDERS.sub(r"\1", out)
    out = _STRIKE.sub(r"\1", out)
    out = _ITALIC_STARS.sub(r"\1", out)
    out = _ITALIC_UNDERS.sub(r"\1", out)
    out = out.replace("**", "")
    out = out.replace("__", "")
    out = out.replace("*", " ")
    return out


def strip_markdown_for_speech(text: str, *, max_chars: int = 0, math_speak: bool = True) -> str:
    """Reduce Markdown to plain prose suitable for TTS.

    Drops code blocks and tables outright (they read terribly), unwraps links
    and emphasis to their visible text, verbalizes LaTeX math so delimiters
    and commands are not read aloud, and removes structural markers. This is
    deliberately lossy — the goal is natural speech, not faithful rendering.

    ``math_speak=False`` still strips ``$`` wrappers but leaves inner TeX
    (``\\frac``, ``^2``) for the voice model to handle itself.
    """
    if not text:
        return ""
    out = _FENCED_CODE.sub(" ", text)
    out = _TABLE_PIPE.sub(" ", out)
    out = _IMAGE.sub(" ", out)
    out = _LINK.sub(r"\1", out)
    out = _INLINE_CODE.sub(r"\1", out)
    out = _HEADING.sub("", out)
    out = _BLOCKQUOTE.sub("", out)
    out = _LIST_MARKER.sub("", out)
    out = _HTML_TAG.sub("", out)
    # Math before emphasis: TeX uses `_` / `*` as scripts and products, and
    # the emphasis regex would otherwise pair a prose underscore with one
    # inside `$x_i$`.
    out = verbalize_latex_for_speech(
        out,
        math_speak=math_speak,
        prose_transform=_unwrap_emphasis_for_speech if not math_speak else None,
    )
    if math_speak:
        out = _unwrap_emphasis_for_speech(out)
    out = _WHITESPACE.sub(" ", out)
    out = _BLANK_LINES.sub("\n\n", out).strip()
    if max_chars and len(out) > max_chars:
        # Cut on a sentence/space boundary near the cap so speech ends cleanly.
        window = out[:max_chars]
        cut = max(window.rfind("."), window.rfind("\n"), window.rfind(" "))
        out = window[: cut + 1].strip() if cut > max_chars // 2 else window.strip()
    return out


__all__ = [
    "TranscriptCue",
    "VoiceProviderError",
    "VoiceProviderHTTPError",
    "VoiceProviderTimeout",
    "synthesize_with_timeout",
    "BaseTTSAdapter",
    "BaseSTTAdapter",
    "build_auth_headers",
    "join_audio_path",
    "normalize_stt_content_type",
    "strip_markdown_for_speech",
]