echospeaks 0.0.1__tar.gz

echospeaks-0.0.1/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+.env
+.pytest_cache/
+dist/
+*.egg-info/
+uv.lock
+.DS_Store

echospeaks-0.0.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,99 @@
+# 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/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",
+]

echospeaks-0.0.1/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",
+]

echospeaks-0.0.1/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()

echospeaks-0.0.1/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()

echospeaks-0.0.1/echovoice/common/__init__.py

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

echospeaks-0.0.1/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")

echospeaks-0.0.1/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)

echospeaks-0.0.1/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

echospeaks-0.0.1/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",
+]