echospeaks 0.0.1__py3-none-any.whl

echospeaks-0.0.1.dist-info/METADATA

@@ -0,0 +1,113 @@
+Metadata-Version: 2.5
+Name: echospeaks
+Version: 0.0.1
+Summary: Sentence-level TTS audio cache for pipecat voice pipelines — in-memory store, cache keying, and EnableTTSCache/TTSCacheCapture pipeline integration
+Author-email: Futwork <om@futwork.com>
+License: Proprietary
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Requires-Dist: aiohttp>=3.9.0
+Provides-Extra: pipecat
+Requires-Dist: pipecat-ai>=1.0.0; extra == 'pipecat'
+Description-Content-Type: text/markdown
+
+# echovoice
+
+Sentence-level TTS audio cache for [pipecat](https://github.com/pipecat-ai/pipecat)
+voice pipelines. **In-memory only for now** — audio captured on one call is
+served on every later call in the same process; no external service, no
+persistence.
+
+## Layout
+
+```
+echovoice/
+  defaults.py   every SDK-wide tunable default, in one place
+  common/       shared dataclasses (CachedAudio, AudioMeta) + logger shim
+  cache/        keying (normalization + cache keys) and the in-memory store
+  pipecat_tts/  pipeline integration — mixin.py (read), capture.py (write),
+                pending.py (read→write handoff), bracket_filter.py (merges
+                per-sentence Started/Stopped into turn-level brackets so the
+                transport behaves like stock); needs pipecat-ai
+  remote/       dormant echo-service HTTP path (client + config)
+```
+
+## How it works
+
+Two pieces, wired around the host's existing TTS service:
+
+- **Read — `EnableTTSCache`** (`echovoice.pipecat_tts.mixin`): drop-in
+  replacement for instantiating the provider class. Every sentence's
+  `run_tts` first checks the shared in-memory store: a **hit** replays the
+  cached PCM as `TTSAudioRawFrame`s (zero provider traffic, barge-in aware),
+  a **miss** synthesizes live and marks the sentence for capture.
+- **Write — `TTSCacheCapture`** (`echovoice.pipecat_tts.capture`): a
+  pass-through processor placed right after the TTS service in the pipeline.
+  It buffers each miss-marked sentence's audio and stores the finished
+  sentence in the shared store (`echovoice.cache.store.AUDIO_STORE`, a bounded
+  LRU map — 500 entries / 200 MB by default). Interruptions discard partial
+  buffers, so truncated audio is never stored.
+
+Cache keys (`echovoice.cache.keying`) hash normalized text + provider + voice
++ model + sample rate, so whitespace/casing never causes a false miss and two
+voices in one process can never serve each other's audio. Normalization is
+for key matching only — synthesis always uses the real text.
+
+ElevenLabs specifics handled by the wrapper (validated against the
+multi-context websocket API):
+
+- One provider context **per sentence**, closed right after its text is sent
+  (close is graceful — the provider flushes the audio, then sends the final).
+- A client-side gate caps simultaneous contexts (default 4 — ElevenLabs kills
+  the socket at >5; tune via `EnableTTSCache(cache_config={"max_concurrent_context": ...,
+  "sentence_wait_timeout_s": ...})`, all defaults live in `echovoice/defaults.py`).
+  Slots free on the context's final, interruption, or websocket reconnect.
+- Cache hits take no context and no gate slot; the replayed context is
+  completed explicitly so the sentence serializer never stalls.
+
+## Install
+
+```bash
+pip install -e /path/to/echovoice             # core (no pipecat needed)
+pip install -e "/path/to/echovoice[pipecat]"  # with the pipecat wrapper
+```
+
+With uv, in the host app's `pyproject.toml`:
+
+```toml
+dependencies = ["echovoice"]
+
+[tool.uv.sources]
+echovoice = { path = "../echovoice", editable = true }
+```
+
+## Usage (fw-aisha style)
+
+```python
+from echovoice.pipecat_tts import EnableTTSCache, TTSCacheCapture
+
+# read side — instead of CustomElevenLabsTTSService(...):
+tts = EnableTTSCache(CustomElevenLabsTTSService,
+    url="wss://api.in.residency.elevenlabs.io",
+    api_key=ELEVENLABS_API_KEY,
+    settings=ElevenLabsTTSService.Settings(model=..., voice=...),
+)
+
+# write side + bracket filter — right after the TTS service in the pipeline:
+pipeline = Pipeline([..., tts, TTSCacheCapture(), TTSTurnBracketFilter(),
+                     transport.output(), ...])
+```
+
+No configuration needed. The wrapped service exposes
+`get_and_reset_turn_stats()` and `log_cache_summary(call_sid=...)` for call
+logs. Skip both pieces and the provider runs fully stock.
+
+`echovoice.remote` holds the HTTP client for a future server-backed cache
+(echo-service); it is dormant — nothing on the active path uses it.
+
+## Tests
+
+```bash
+uv sync && uv run pytest
+```

echospeaks-0.0.1.dist-info/RECORD

@@ -0,0 +1,19 @@
+echovoice/__init__.py,sha256=b1deXn2Pgmx1OH8l_N07AeXdw030UDdDW42Jo9vzwPE,1026
+echovoice/defaults.py,sha256=EBgsFDE3jkbgFKeq6SsWc9SqgNtY86Nrt8rmlPUMvRM,1630
+echovoice/cache/__init__.py,sha256=14GeUAAs0MqtndFCd7K9BCF_BlQ68bFpWtAJylmwEjQ,270
+echovoice/cache/keying.py,sha256=D2tqOnS1PwuP65Bqo8F8QHbeivA5g99hCGDpl34h6MU,3669
+echovoice/cache/store.py,sha256=7xkBTkhlPXXz0YXUK2EDnVlFrKpk6QVmZS2wbQGINwY,3465
+echovoice/common/__init__.py,sha256=oMSIcb0q-bjgp9516PT3CpA99GnOn2Rx5ZF4J-asARA,117
+echovoice/common/log.py,sha256=ZT48yRFZdP_W1nyLMYFZEpHo08hn3mqTXgdkZrB8OI8,232
+echovoice/common/models.py,sha256=xfdrn8seoeBNI9KMqWeGbFdCKCan4CP-HY58bRNEy0o,1448
+echovoice/pipecat_tts/__init__.py,sha256=5YkSr1NzGTL7H0QQCb6jj06SuMd2U9jNFbnziFnaysM,1214
+echovoice/pipecat_tts/bracket_filter.py,sha256=2wMF6yHOI_pz2thyJj7PIWHOJMizlU5pB6wDwChDMAU,6917
+echovoice/pipecat_tts/capture.py,sha256=GWnmvSIMHK0NviD80nu11SerH9TqflwyaUD1NaB_xaY,4367
+echovoice/pipecat_tts/mixin.py,sha256=1AI2GWHOztlxBkFk2cM8VFbw8_QgWz_mFybjOQ2QqL0,16789
+echovoice/pipecat_tts/pending.py,sha256=ngSsSg4cjnwiU4HMQMkkNqIerH1C2NzxNuY1yU2-a7A,1515
+echovoice/remote/__init__.py,sha256=IiKn9KCZzkrr6h0X_JxwH3Z-p4e0goPp5i4MOXZy-4k,420
+echovoice/remote/client.py,sha256=5cPP6gPhGZWVnN77sU8lRsGSgpSgYMBDYpMaEGo0r70,5161
+echovoice/remote/config.py,sha256=LUCUgtThK3rlHwtWCLn2wKkLOfvtbkZDzjoYVijaVPs,1651
+echospeaks-0.0.1.dist-info/METADATA,sha256=3UDfYxOV7xafc_JjcZgZhYvkpSe-lQTHRNMa5CWm6cs,4561
+echospeaks-0.0.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+echospeaks-0.0.1.dist-info/RECORD,,

echospeaks-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

echovoice/__init__.py

@@ -0,0 +1,27 @@
+"""
+echovoice — sentence-level TTS audio cache for pipecat voice pipelines.
+
+Package layout:
+    defaults.py   every SDK-wide tunable default, in one place
+    common/       shared dataclasses (CachedAudio, AudioMeta) + logger shim
+    cache/        keying (normalization + cache keys) and the in-memory store
+    pipecat_tts/  the pipeline integration: EnableTTSCache (read) and
+                  TTSCacheCapture (write) — import explicitly, needs pipecat-ai
+    remote/       dormant echo-service HTTP path for a future server-backed cache
+
+echovoice.pipecat_tts is not re-exported here so the core SDK stays
+import-safe without pipecat installed.
+"""
+from .cache.keying import generate_cache_key, normalize_for_cache, settings_signature
+from .cache.store import AUDIO_STORE, InMemoryAudioStore
+from .common.models import AudioMeta, CachedAudio
+
+__all__ = [
+    "AUDIO_STORE",
+    "AudioMeta",
+    "CachedAudio",
+    "InMemoryAudioStore",
+    "generate_cache_key",
+    "normalize_for_cache",
+    "settings_signature",
+]

echovoice/cache/__init__.py

@@ -0,0 +1,10 @@
+from .keying import generate_cache_key, normalize_for_cache, settings_signature
+from .store import AUDIO_STORE, InMemoryAudioStore
+
+__all__ = [
+    "AUDIO_STORE",
+    "InMemoryAudioStore",
+    "generate_cache_key",
+    "normalize_for_cache",
+    "settings_signature",
+]

echovoice/cache/keying.py

@@ -0,0 +1,99 @@
+"""
+Cache-key text normalization + key generation (shared by all providers).
+
+IMPORTANT: normalization is for KEY MATCHING ONLY. Audio is always synthesized
+from the real, punctuated text + real settings — never from the normalized key.
+"""
+import hashlib
+import json
+import re
+import unicodedata
+
+# ── text normalization ────────────────────────────────────────────────────────
+
+_ZERO_WIDTH = {"​", "‌", "‍", ""}
+_KEEP_PUNCT = {"?", "!"}                      # prosodic — keep
+_APOSTROPHES = set("'’‘\"“”`")                # drop, no space (contractions)
+
+_REPEAT_MARK = re.compile(r"([?!])\1+")        # "??" -> "?"
+_SPACE_BEFORE_MARK = re.compile(r"\s+([?!])")  # "ok ?" -> "ok?"
+
+
+def normalize_for_cache(text: str) -> str:
+    if not text:
+        return ""
+    text = unicodedata.normalize("NFC", text).lower()
+    chars = list(text)
+    n = len(chars)
+    out = []
+    for i, ch in enumerate(chars):
+        if ch in _ZERO_WIDTH or ch in _APOSTROPHES:
+            continue
+        if ch in _KEEP_PUNCT:
+            out.append(ch)
+            continue
+        prev = chars[i - 1] if i > 0 else ""
+        nxt = chars[i + 1] if i + 1 < n else ""
+        if ch in (",", "."):
+            out.append(ch if (prev.isdigit() and nxt.isdigit()) else " ")
+            continue
+        if ch == "%":
+            out.append("%" if prev.isdigit() else " ")
+            continue
+        cat = unicodedata.category(ch)
+        if cat == "Sc":  # currency symbol next to a number
+            out.append(ch if (prev.isdigit() or nxt.isdigit()) else " ")
+            continue
+        out.append(" " if cat[0] in ("P", "S") else ch)  # keep L/M/N + space
+    text = "".join(out)
+    text = _REPEAT_MARK.sub(r"\1", text)
+    text = _SPACE_BEFORE_MARK.sub(r"\1", text)
+    return " ".join(text.split())
+
+
+# ── settings signature ────────────────────────────────────────────────────────
+
+_AUDIO_SETTING_KEYS = frozenset({
+    "speed", "stability", "similarity_boost", "style", "use_speaker_boost",
+    "language", "controls", "emotion", "pitch", "pronunciation_dict_id",
+})
+
+
+def _canon(v):
+    if isinstance(v, float):
+        return round(v, 6)
+    if isinstance(v, dict):
+        return {k: _canon(v[k]) for k in sorted(v)}
+    if isinstance(v, (list, tuple)):
+        return [_canon(x) for x in v]
+    return v
+
+
+def settings_signature(settings: dict | None) -> str:
+    """Canonical 12-char hash of the audio-affecting settings only."""
+    if not settings:
+        return ""
+    sig = {k: _canon(settings[k]) for k in sorted(settings)
+           if k in _AUDIO_SETTING_KEYS and settings.get(k) is not None}
+    if not sig:
+        return ""
+    return hashlib.sha256(json.dumps(sig, sort_keys=True).encode("utf-8")).hexdigest()[:12]
+
+
+# ── key generation ────────────────────────────────────────────────────────────
+
+def generate_cache_key(
+    text: str,
+    *,
+    provider: str,
+    voice_id: str,
+    model_id: str,
+    sample_rate: int = 16000,
+    num_channels: int = 1,
+    encoding: str = "pcm_s16le",
+    settings: dict | None = None,
+) -> str:
+    normalized = normalize_for_cache(text)
+    sig = settings_signature(settings)
+    raw = f"{provider}:{model_id}:{voice_id}:{sample_rate}:{num_channels}:{encoding}:{sig}:{normalized}"
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()

echovoice/cache/store.py

@@ -0,0 +1,94 @@
+"""
+In-memory TTS audio store shared by the read side (EnableTTSCache) and the
+write side (TTSCacheCapture).
+
+Process-wide by design: a sentence captured on one call is served on every
+later call in the same process. In-memory only for now — no persistence, no
+external service; a Redis/echo-service backend can slot in behind the same
+get/put surface later.
+"""
+import time
+from collections import OrderedDict
+
+from ..common.log import logger
+from ..common.models import CachedAudio
+from ..defaults import STORE_MAX_BYTES, STORE_MAX_ENTRIES
+
+
+class InMemoryAudioStore:
+    """Bounded LRU map: cache key -> CachedAudio. Newest capture wins."""
+
+    def __init__(self, max_entries: int = STORE_MAX_ENTRIES,
+                 max_bytes: int = STORE_MAX_BYTES):
+        self._max_entries = max_entries
+        self._max_bytes = max_bytes
+        self._entries: "OrderedDict[str, CachedAudio]" = OrderedDict()
+        self._total_bytes = 0
+        # Process-wide lookup counters, recorded by the read side (note_hit /
+        # note_miss) so a rate-mismatched lookup counts as a miss, not a hit.
+        self.total_hits = 0
+        self.total_misses = 0
+
+    def get(self, key: str) -> CachedAudio | None:
+        entry = self._entries.get(key)
+        if entry is not None:
+            self._entries.move_to_end(key)  # LRU touch
+        return entry
+
+    def put(self, entry: CachedAudio) -> None:
+        if not entry.key or not entry.audio:
+            return
+        old = self._entries.pop(entry.key, None)
+        if old is not None:
+            self._total_bytes -= len(old.audio)
+            entry.hits += old.hits  # re-capture keeps the sentence's serve count
+        if not entry.captured_at:
+            entry.captured_at = time.time()
+        self._entries[entry.key] = entry
+        self._total_bytes += len(entry.audio)
+        while self._entries and (
+            len(self._entries) > self._max_entries or self._total_bytes > self._max_bytes
+        ):
+            evicted_key, evicted = self._entries.popitem(last=False)
+            self._total_bytes -= len(evicted.audio)
+            logger.debug(f"TTS_CACHE evicted key={evicted_key[:12]} bytes={len(evicted.audio)}")
+
+    def delete(self, key: str) -> bool:
+        """Remove one entry (e.g. via the host's inspection endpoint, to
+        re-create miss scenarios). Returns True if the entry existed."""
+        entry = self._entries.pop(key, None)
+        if entry is None:
+            return False
+        self._total_bytes -= len(entry.audio)
+        return True
+
+    def note_hit(self, entry: CachedAudio) -> None:
+        """Record that this entry was served from the cache."""
+        entry.hits += 1
+        self.total_hits += 1
+
+    def note_miss(self) -> None:
+        """Record a lookup that ended in live synthesis."""
+        self.total_misses += 1
+
+    def snapshot(self) -> list[CachedAudio]:
+        """Current entries, most recently used/stored first. Read-only view for
+        inspection endpoints/debugging — does not touch LRU order."""
+        return list(reversed(self._entries.values()))
+
+    def clear(self) -> None:
+        self._entries.clear()
+        self._total_bytes = 0
+        self.total_hits = 0
+        self.total_misses = 0
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+    @property
+    def total_bytes(self) -> int:
+        return self._total_bytes
+
+
+# The process-wide store both pipeline pieces use.
+AUDIO_STORE = InMemoryAudioStore()

echovoice/common/__init__.py

@@ -0,0 +1,4 @@
+from .log import logger
+from .models import AudioMeta, CachedAudio
+
+__all__ = ["AudioMeta", "CachedAudio", "logger"]

echovoice/common/log.py

@@ -0,0 +1,7 @@
+"""Logger shim: ride the host app's loguru if present, else stdlib logging."""
+try:
+    from loguru import logger  # noqa: F401
+except ImportError:  # pragma: no cover
+    import logging
+
+    logger = logging.getLogger("echovoice")

echovoice/common/models.py

@@ -0,0 +1,39 @@
+"""Shared dataclasses used across the SDK."""
+from dataclasses import dataclass, field
+
+
+@dataclass
+class CachedAudio:
+    """One cached sentence: the PCM plus enough metadata to replay it."""
+
+    key: str            # full cache key (provider/voice/model/rate/text)
+    text: str           # raw sentence text, kept for logs/debugging only
+    audio: bytes        # PCM s16le
+    sample_rate: int
+    num_channels: int = 1
+    captured_at: float = 0.0
+    hits: int = 0       # times this entry was served (see store.note_hit)
+    # Word timings captured off the live synthesis, as (word, seconds from
+    # sentence start). Replayed on a hit so the transcript/context is built
+    # word-by-word exactly like a live sentence; None when never captured.
+    word_times: list | None = None
+    words_include_spaces: bool = False  # TTSTextFrame.includes_inter_frame_spaces
+
+    @property
+    def duration_s(self) -> float:
+        return len(self.audio) / (max(self.sample_rate, 1) * 2 * max(self.num_channels, 1))
+
+
+@dataclass
+class AudioMeta:
+    """Synthesis parameters shipped with a generation job so echo-service can
+    re-create the audio server-side (the cache key is a hash — not reversible).
+    Used only by the dormant remote (echo-service) path."""
+
+    provider: str
+    voice_id: str
+    model_id: str
+    sample_rate: int
+    num_channels: int = 1
+    encoding: str = "pcm_s16le"
+    settings: dict = field(default_factory=dict)

echovoice/defaults.py

@@ -0,0 +1,31 @@
+"""
+Every SDK-wide tunable default in one place.
+
+Hosts override the gate/registry values per instance via
+EnableTTSCache(cache_config={...}) — see echovoice.pipecat_tts.mixin. Any key
+missing from cache_config falls back to the value here.
+"""
+
+# ── context gate (echovoice.pipecat_tts.mixin) ────────────────────────────────
+# ElevenLabs allows at most 5 simultaneous contexts per websocket; exceeding it
+# is a 1008 policy violation that kills the whole socket. Stay one below.
+MAX_CONCURRENT_CONTEXT = 4
+
+# Longest a sentence waits at a full gate. A context's final normally lands
+# 150-300ms after close; if no slot has freed in this long, assume the finals
+# were lost (e.g. socket died) and reclaim every slot.
+SENTENCE_WAIT_TIMEOUT_S = 3.0
+
+# ── hit replay (echovoice.pipecat_tts.mixin) ──────────────────────────────────
+# Cached PCM is replayed in slices of this many bytes (~30ms @ 16kHz mono
+# s16le) so a barge-in can stop the replay between slices.
+REPLAY_CHUNK_BYTES = 960
+
+# ── pending-capture registry (echovoice.pipecat_tts.pending) ──────────────────
+# Bound on the read→write handoff registry; marks whose contexts never finish
+# (dead socket, interruption races) age out past this many entries.
+PENDING_MAX_ENTRIES = 512
+
+# ── in-memory audio store (echovoice.cache.store) ─────────────────────────────
+STORE_MAX_ENTRIES = 500
+STORE_MAX_BYTES = 200 * 1024 * 1024

echovoice/pipecat_tts/__init__.py

@@ -0,0 +1,33 @@
+"""
+Sentence-level TTS cache for pipecat pipelines. In-memory, two pieces:
+
+READ  — EnableTTSCache(ProviderClass, ...) (mixin.py): drop-in replacement
+        for ProviderClass(...). Hits replay cached PCM with zero provider
+        traffic; misses synthesize live and are marked for capture.
+
+WRITE — TTSCacheCapture() (capture.py): a pass-through processor placed right
+        after the TTS service in the pipeline; stores each miss-marked
+        sentence's finished audio in the shared store.
+
+Host integration is two lines:
+
+    tts = EnableTTSCache(CustomElevenLabsTTSService, url=..., api_key=..., settings=...)
+    pipeline = Pipeline([..., tts, TTSCacheCapture(), transport.output(), ...])
+
+Requires pipecat-ai (install extra: echovoice[pipecat]); the rest of the SDK
+imports without it.
+"""
+from ..defaults import MAX_CONCURRENT_CONTEXT, SENTENCE_WAIT_TIMEOUT_S
+from .bracket_filter import TTSTurnBracketFilter
+from .capture import TTSCacheCapture
+from .mixin import EnableTTSCache, TTSCacheMixin, make_cached
+
+__all__ = [
+    "EnableTTSCache",
+    "MAX_CONCURRENT_CONTEXT",
+    "SENTENCE_WAIT_TIMEOUT_S",
+    "TTSCacheCapture",
+    "TTSCacheMixin",
+    "TTSTurnBracketFilter",
+    "make_cached",
+]

echovoice/pipecat_tts/bracket_filter.py

@@ -0,0 +1,155 @@
+"""
+TTSTurnBracketFilter — coalesces per-sentence Started/Stopped brackets into
+one turn-level bracket, restoring stock pipecat semantics downstream.
+
+Per-sentence contexts (the cache's read side) make the TTS service emit a
+TTSStartedFrame/TTSStoppedFrame pair PER SENTENCE. The output transport
+treats every Stopped as "bot stopped speaking", so bot-speaking state flaps
+at each sentence boundary: noisy logs, per-sentence bot started/stopped
+events, VAD-only barge-in windows between sentences, and confused turn
+metrics. Stock pipecat (one context per turn) emits ONE bracket per turn —
+which is what every downstream consumer was designed for.
+
+This processor sits AFTER TTSCacheCapture (which needs the per-sentence
+Stops) and BEFORE transport.output(). It forwards the turn's first Started,
+swallows intermediate Stopped/Started pairs, and releases only the final
+Stopped:
+
+    in:  S1▶ audio S1■ S2▶ audio S2■ S3▶ audio S3■
+    out: S1▶ audio       audio       audio      S3■
+
+"Is this the final Stopped?" is answered by asking the TTS SERVICE, not by
+watching frame order. (Frame markers lie here: pipecat re-pushes the
+LLMFullResponseEndFrame at the end of the FIRST context — see
+tts_service._handle_llm_response_end — so in per-sentence mode the End
+marker passes downstream after sentence 1, not after the last sentence.)
+The service holds the truth:
+  - _turn_context_id      not None  → the LLM turn is still producing text
+  - _serialization_queue  non-empty → more sentence contexts queued to play
+  - _playing_context_id             → the context the serializer is draining;
+                                      if it moved past the held Stop's
+                                      context, another sentence is under way
+The held Stopped is released only when none of those indicate pending
+speech. Release is re-checked when a Stopped arrives and when an
+LLMFullResponseEndFrame passes (covers the last sentence finishing playout
+before the LLM turn was fully flushed).
+
+Interruption: the InterruptionFrame bypasses this filter's bookkeeping
+entirely (the transport declares bot-stopped from the interruption itself),
+so on interruption we just reset — drop any held Stopped, ignore stray
+Stops until the next Started — and pass the frame through untouched.
+"""
+from pipecat.frames.frames import (
+    Frame,
+    InterruptionFrame,
+    LLMFullResponseEndFrame,
+    LLMFullResponseStartFrame,
+    TTSStartedFrame,
+    TTSStoppedFrame,
+)
+from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
+
+from ..common.log import logger
+
+
+class TTSTurnBracketFilter(FrameProcessor):
+    """Merge per-sentence TTS Started/Stopped brackets into per-turn ones.
+
+    Args:
+        tts: the (cache-wrapped) TTS service instance from the same pipeline.
+            Consulted read-only to decide whether more sentences are pending
+            in the current turn. Without it the filter cannot know, and
+            passes every bracket through unmerged (stock flapping behavior).
+    """
+
+    def __init__(self, tts=None):
+        super().__init__()
+        self._tts = tts
+        self._warned_no_tts = False
+        self._run_open = False                       # forwarded Started, Stopped pending
+        self._held_stop: TTSStoppedFrame | None = None
+
+    async def process_frame(self, frame: Frame, direction: FrameDirection):
+        await super().process_frame(frame, direction)
+        if direction != FrameDirection.DOWNSTREAM:
+            await self.push_frame(frame, direction)
+            return
+        for out in self._transform(frame):
+            await self.push_frame(out, direction)
+
+    # ── pure frame logic (returns the frames to forward, in order) ──────────
+
+    def _transform(self, frame: Frame) -> list[Frame]:
+        if isinstance(frame, InterruptionFrame):
+            # The transport handles bot-stopped itself on interruption; any
+            # held Stopped belongs to a turn that no longer exists.
+            self._reset()
+            return [frame]
+
+        if isinstance(frame, LLMFullResponseStartFrame):
+            out = []
+            if self._held_stop is not None:
+                # Previous run never released (e.g. turn died mid-generation)
+                # — close its bracket before the new turn begins.
+                logger.debug("TTS_BRACKET closing stale bracket at new turn start")
+                out.append(self._held_stop)
+                self._reset()
+            out.append(frame)
+            return out
+
+        if isinstance(frame, LLMFullResponseEndFrame):
+            # Not a reliable end-of-speech marker (see module docstring), but
+            # a good moment to re-check the service state.
+            return [frame] + self._maybe_release()
+
+        if isinstance(frame, TTSStartedFrame):
+            self._held_stop = None  # another sentence follows: held stop was intermediate
+            if not self._run_open:
+                self._run_open = True
+                return [frame]      # first Started of the turn passes
+            return []               # intermediate Started swallowed
+
+        if isinstance(frame, TTSStoppedFrame):
+            if not self._run_open:
+                return []           # stray stop after interruption/reset
+            self._held_stop = frame
+            return self._maybe_release()
+
+        return [frame]
+
+    # ── turn-pending check against the TTS service ──────────────────────────
+
+    def _more_speech_pending(self) -> bool:
+        svc = self._tts
+        if svc is None:
+            if not self._warned_no_tts:
+                self._warned_no_tts = True
+                logger.warning(
+                    "TTS_BRACKET no tts service reference — cannot detect "
+                    "turn end, passing brackets through unmerged"
+                )
+            return False
+        # The LLM turn is still aggregating/flushing sentences.
+        if getattr(svc, "_turn_context_id", None) is not None:
+            return True
+        # More sentence contexts queued behind the one that just drained.
+        queue = getattr(svc, "_serialization_queue", None)
+        if queue is not None and not queue.empty():
+            return True
+        # The serializer already moved on to draining another context.
+        playing = getattr(svc, "_playing_context_id", None)
+        held_ctx = self._held_stop.context_id if self._held_stop else None
+        if playing is not None and playing != held_ctx:
+            return True
+        return False
+
+    def _maybe_release(self) -> list[Frame]:
+        if self._held_stop is not None and not self._more_speech_pending():
+            stop = self._held_stop
+            self._reset()
+            return [stop]
+        return []
+
+    def _reset(self) -> None:
+        self._run_open = False
+        self._held_stop = None