dv-pipecat-ai 0.0.85.dev847__tar.gz → 0.0.85.dev850__tar.gz

{dv_pipecat_ai-0.0.85.dev847 → dv_pipecat_ai-0.0.85.dev850}/CHANGELOG.md

@@ -12,6 +12,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - It is now possible to start a bot from the `/start` endpoint when using the
   runner Daily's transport. This follows the Pipecat Cloud format with
   `createDailyRoom` and `body` fields in the POST request body.
+- Added `ElevenLabsRealtimeSTTService`, enabling native integration with the
+  `scribe_v2_realtime` WebSocket API (manual and VAD commit strategies, partial
+  frames, and word-timestamp forwarding).
 
 - Added an ellipsis character (`…`) to the end of sentence detection in the
   string utils.

{dv_pipecat_ai-0.0.85.dev847 → dv_pipecat_ai-0.0.85.dev850}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dv-pipecat-ai
-Version: 0.0.85.dev847
+Version: 0.0.85.dev850
 Summary: An open source framework for voice (and multimodal) assistants
 License-Expression: BSD-2-Clause
 Project-URL: Source, https://github.com/pipecat-ai/pipecat

{dv_pipecat_ai-0.0.85.dev847 → dv_pipecat_ai-0.0.85.dev850}/src/dv_pipecat_ai.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dv-pipecat-ai
-Version: 0.0.85.dev847
+Version: 0.0.85.dev850
 Summary: An open source framework for voice (and multimodal) assistants
 License-Expression: BSD-2-Clause
 Project-URL: Source, https://github.com/pipecat-ai/pipecat

{dv_pipecat_ai-0.0.85.dev847 → dv_pipecat_ai-0.0.85.dev850}/src/pipecat/frames/frames.py

@@ -586,6 +586,27 @@ class LLMRunFrame(DataFrame):
     pass
 
 
+@dataclass
+class WarmupLLMFrame(DataFrame):
+    """Frame to trigger prompt caching/warmup in supported LLM providers.
+
+    This frame instructs the LLM service to cache the provided messages
+    without generating a visible response. Primarily used for warming up provider
+    caches (e.g., Claude's prompt caching, OpenAI's prompt caching) to improve
+    latency for subsequent requests.
+
+    The LLM service should:
+    1. Send the messages to the provider to trigger caching
+    2. Generate a minimal response (e.g., single word)
+    3. Discard the response without emitting LLM output frames
+
+    Parameters:
+        messages: List of messages to send for cache warming (should match conversation structure).
+    """
+
+    messages: List[dict]
+
+
 @dataclass
 class LLMMessagesAppendFrame(DataFrame):
     """Frame containing LLM messages to append to current context.

{dv_pipecat_ai-0.0.85.dev847 → dv_pipecat_ai-0.0.85.dev850}/src/pipecat/services/deepgram/stt.py

@@ -8,7 +8,11 @@
 
 import asyncio
 import logging
-from typing import AsyncGenerator, Dict, Optional
+import os
+import socket
+import time
+from typing import AsyncGenerator, Callable, Dict, Optional
+from urllib.parse import urlparse
 
 from loguru import logger
 
@@ -29,6 +33,155 @@ from pipecat.transcriptions.language import Language
 from pipecat.utils.time import time_now_iso8601
 from pipecat.utils.tracing.service_decorators import traced_stt
 
+_PROCESS_START_MONOTONIC = time.monotonic()
+
+
+def _read_first_numeric_file(paths):
+    for path in paths:
+        try:
+            with open(path, "r", encoding="utf-8") as file:
+                value = file.read().strip()
+        except FileNotFoundError:
+            continue
+        except OSError:
+            continue
+
+        if not value or value == "max":
+            return None
+
+        try:
+            return int(value)
+        except ValueError:
+            continue
+    return None
+
+
+def _read_proc_status_value(key):
+    try:
+        with open("/proc/self/status", "r", encoding="utf-8") as status_file:
+            for line in status_file:
+                if line.startswith(key):
+                    parts = line.split()
+                    if len(parts) >= 2:
+                        return int(parts[1]) * 1024  # kB -> bytes
+    except FileNotFoundError:
+        return None
+    except OSError:
+        return None
+    return None
+
+
+def _read_cpu_throttling():
+    paths = ["/sys/fs/cgroup/cpu.stat", "/sys/fs/cgroup/cpu/cpu.stat"]
+    for path in paths:
+        try:
+            with open(path, "r", encoding="utf-8") as cpu_file:
+                for line in cpu_file:
+                    if line.startswith("nr_throttled"):
+                        parts = line.split()
+                        if len(parts) >= 2:
+                            return int(parts[1])
+        except FileNotFoundError:
+            continue
+        except OSError:
+            continue
+    return None
+
+
+def _collect_runtime_diagnostics(
+    loop: Optional[asyncio.AbstractEventLoop] = None,
+    extra_context: Optional[Dict] = None,
+    context_provider: Optional[Callable[[], Dict]] = None,
+):
+    if loop is None:
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            loop = None
+
+    uptime_s = round(time.monotonic() - _PROCESS_START_MONOTONIC, 1)
+    rss_bytes = _read_proc_status_value("VmRSS:")
+    rss_mb = round(rss_bytes / (1024**2), 2) if rss_bytes else None
+
+    cgroup_usage_bytes = _read_first_numeric_file(
+        ["/sys/fs/cgroup/memory.current", "/sys/fs/cgroup/memory/memory.usage_in_bytes"]
+    )
+    cgroup_limit_bytes = _read_first_numeric_file(
+        ["/sys/fs/cgroup/memory.max", "/sys/fs/cgroup/memory/memory.limit_in_bytes"]
+    )
+    cgroup_usage_mb = (
+        round(cgroup_usage_bytes / (1024**2), 2) if cgroup_usage_bytes is not None else None
+    )
+    cgroup_limit_mb = (
+        round(cgroup_limit_bytes / (1024**2), 2) if cgroup_limit_bytes not in (None, 0) else None
+    )
+    cgroup_pct = (
+        round(cgroup_usage_bytes / cgroup_limit_bytes * 100, 2)
+        if cgroup_usage_bytes is not None and cgroup_limit_bytes not in (None, 0)
+        else None
+    )
+
+    try:
+        open_fds = len(os.listdir("/proc/self/fd"))
+    except Exception:
+        open_fds = None
+
+    pending_tasks = None
+    if loop:
+        try:
+            pending_tasks = len(asyncio.all_tasks(loop))
+        except Exception:
+            pending_tasks = None
+
+    suspected_cause = "unknown"
+    if cgroup_pct and cgroup_pct >= 90:
+        suspected_cause = "memory_pressure"
+    elif uptime_s < 180:
+        suspected_cause = "pod_cold_start"
+
+    diagnostics = {
+        "uptime_s": uptime_s,
+        "rss_mb": rss_mb,
+        "cgroup_usage_mb": cgroup_usage_mb,
+        "cgroup_limit_mb": cgroup_limit_mb,
+        "cgroup_usage_pct": cgroup_pct,
+        "open_fds": open_fds,
+        "pending_tasks": pending_tasks,
+        "suspected_cause": suspected_cause,
+    }
+    cpu_throttled = _read_cpu_throttling()
+    if cpu_throttled is not None:
+        diagnostics["cpu_nr_throttled"] = cpu_throttled
+
+    if context_provider:
+        try:
+            ctx = context_provider() or {}
+            if isinstance(ctx, dict):
+                diagnostics.update({k: v for k, v in ctx.items() if v is not None})
+        except Exception as exc:
+            diagnostics["context_provider_error"] = str(exc)
+
+    if extra_context:
+        diagnostics.update({k: v for k, v in extra_context.items() if v is not None})
+
+    return {k: v for k, v in diagnostics.items() if v is not None}
+
+
+def _derive_connect_endpoint(base_url: str):
+    if not base_url:
+        return "api.deepgram.com", 443
+
+    parsed = urlparse(base_url)
+    host = parsed.hostname or "api.deepgram.com"
+    if parsed.port:
+        port = parsed.port
+    elif parsed.scheme in ("https", "wss"):
+        port = 443
+    else:
+        port = 80
+    return host, port
+
+
 try:
     from deepgram import (
         AsyncListenWebSocketClient,
@@ -64,6 +217,7 @@ class DeepgramSTTService(STTService):
         addons: Optional[Dict] = None,
         max_connect_retries: int = 3,
         connect_timeout_s: float = 2.5,
+        diagnostics_context_provider: Optional[Callable[[], Dict]] = None,
         **kwargs,
     ):
         """Initialize the Deepgram STT service.
@@ -82,6 +236,9 @@ class DeepgramSTTService(STTService):
             max_connect_retries: Maximum number of connection attempts before giving up.
             connect_timeout_s: Maximum time in seconds to wait for a connection attempt.
                 Connection retries wait 100ms between attempts.
+            diagnostics_context_provider: Optional callable returning a dict with
+                additional runtime diagnostics (e.g., active call counts) to append
+                to warning logs.
             **kwargs: Additional arguments passed to the parent STTService.
         """
         sample_rate = sample_rate or (live_options.sample_rate if live_options else None)
@@ -125,6 +282,7 @@ class DeepgramSTTService(STTService):
         self.set_model_name(merged_options["model"])
         self._settings = merged_options
         self._addons = addons
+        self._diagnostics_context_provider = diagnostics_context_provider
 
         # Connection retry settings (100ms delay between retries)
         self._max_connect_retries = max_connect_retries
@@ -142,6 +300,7 @@ class DeepgramSTTService(STTService):
                 verbose=logging.ERROR,  # Enable error level and above logging
             ),
         )
+        self._connect_host, self._connect_port = _derive_connect_endpoint(base_url)
 
         if self.vad_enabled:
             self._register_event_handler("on_speech_started")
@@ -230,7 +389,10 @@ class DeepgramSTTService(STTService):
     async def _connect(self):
         self.logger.debug("Attempting to connect to Deepgram...")
 
+        loop = asyncio.get_running_loop()
         for attempt in range(self._max_connect_retries):
+            attempt_started = time.perf_counter()
+            dns_ms = await self._measure_dns_resolution(loop)
             try:
                 # Clean up any previous connection attempt in background (non-blocking)
                 if hasattr(self, "_connection") and self._connection is not None:
@@ -266,18 +428,67 @@ class DeepgramSTTService(STTService):
                         timeout=self._connect_timeout_s,
                     )
                 except asyncio.TimeoutError:
+                    elapsed_ms = round((time.perf_counter() - attempt_started) * 1000, 2)
+                    diagnostics = _collect_runtime_diagnostics(
+                        loop,
+                        extra_context={
+                            "dns_ms": dns_ms,
+                            "connect_duration_ms": elapsed_ms,
+                        },
+                        context_provider=self._diagnostics_context_provider,
+                    )
                     self.logger.warning(
-                        f"Deepgram connection attempt {attempt + 1}/{self._max_connect_retries} timed out after {self._connect_timeout_s} second(s)."
+                        (
+                            "Deepgram connection attempt {}/{} timed out after {:.2f} second(s). "
+                            "runtime_diagnostics={}"
+                        ),
+                        attempt + 1,
+                        self._max_connect_retries,
+                        self._connect_timeout_s,
+                        diagnostics,
                     )
                     start_result = False
                 except Exception as start_error:
+                    elapsed_ms = round((time.perf_counter() - attempt_started) * 1000, 2)
+                    diagnostics = _collect_runtime_diagnostics(
+                        loop,
+                        extra_context={
+                            "dns_ms": dns_ms,
+                            "connect_duration_ms": elapsed_ms,
+                        },
+                        context_provider=self._diagnostics_context_provider,
+                    )
                     self.logger.warning(
-                        f"Deepgram connection attempt {attempt + 1}/{self._max_connect_retries} failed with an exception: {start_error}"
+                        (
+                            "Deepgram connection attempt {}/{} failed with an exception: {}. "
+                            "runtime_diagnostics={}"
+                        ),
+                        attempt + 1,
+                        self._max_connect_retries,
+                        start_error,
+                        diagnostics,
                     )
                     start_result = False
                 else:
                     if start_result:
-                        self.logger.info("Successfully connected to Deepgram.")
+                        elapsed_ms = round((time.perf_counter() - attempt_started) * 1000, 2)
+                        diagnostics = _collect_runtime_diagnostics(
+                            loop,
+                            extra_context={
+                                "dns_ms": dns_ms,
+                                "connect_duration_ms": elapsed_ms,
+                            },
+                            context_provider=self._diagnostics_context_provider,
+                        )
+                        self.logger.info(
+                            (
+                                "Successfully connected to Deepgram on attempt {} in {:.2f} ms. "
+                                "runtime_diagnostics={}"
+                            ),
+                            attempt + 1,
+                            elapsed_ms,
+                            diagnostics,
+                        )
                         return  # Exit the method on success
 
                 self.logger.warning(
@@ -285,8 +496,24 @@ class DeepgramSTTService(STTService):
                 )
 
             except Exception as e:
+                elapsed_ms = round((time.perf_counter() - attempt_started) * 1000, 2)
+                diagnostics = _collect_runtime_diagnostics(
+                    loop,
+                    extra_context={
+                        "dns_ms": dns_ms,
+                        "connect_duration_ms": elapsed_ms,
+                    },
+                    context_provider=self._diagnostics_context_provider,
+                )
                 self.logger.warning(
-                    f"Deepgram connection attempt {attempt + 1}/{self._max_connect_retries} failed with an exception: {e}"
+                    (
+                        "Deepgram connection attempt {}/{} failed with an exception: {}. "
+                        "runtime_diagnostics={}"
+                    ),
+                    attempt + 1,
+                    self._max_connect_retries,
+                    e,
+                    diagnostics,
                 )
 
             # If this is not the last attempt, wait 100ms before retrying
@@ -300,6 +527,22 @@ class DeepgramSTTService(STTService):
         self.logger.error(error_msg)
         await self.push_error(ErrorFrame(error_msg, fatal=True))
 
+    async def _measure_dns_resolution(self, loop: Optional[asyncio.AbstractEventLoop]):
+        if not loop or not self._connect_host:
+            return None
+        try:
+            dns_task = loop.getaddrinfo(
+                self._connect_host,
+                self._connect_port,
+                type=socket.SOCK_STREAM,
+                proto=socket.IPPROTO_TCP,
+            )
+            start = time.perf_counter()
+            await asyncio.wait_for(dns_task, timeout=1.0)
+            return round((time.perf_counter() - start) * 1000, 2)
+        except Exception:
+            return None
+
     async def _disconnect(self):
         # Guard against missing connection instance and ensure proper async check
         connection: AsyncListenWebSocketClient = getattr(self, "_connection", None)