deepctl-cmd-debug-probe 0.0.2__py3-none-any.whl

deepctl_cmd_debug_probe/__init__.py

@@ -0,0 +1,5 @@
+"""Debug probe subcommand for deepctl — live ffprobe analysis during streaming."""
+
+from .command import ProbeCommand
+
+__all__ = ["ProbeCommand"]

deepctl_cmd_debug_probe/command.py

@@ -0,0 +1,207 @@
+"""Debug probe command for deepctl — WebSocket proxy with live ffprobe analysis."""
+
+from __future__ import annotations
+
+import asyncio
+import socket
+import time
+from typing import Any
+
+from aiohttp import web
+from deepctl_core import AuthManager, BaseCommand, Config, DeepgramClient
+from deepctl_shared_utils import require_ffprobe
+from rich.console import Console
+from rich.panel import Panel
+
+from .models import ProbeDebugResult
+from .proxy import ProbeProxy
+
+console = Console()
+
+
+def _find_available_port(start: int = 3100, end: int = 3199) -> int | None:
+    """Find an available port in the given range."""
+    for port in range(start, end + 1):
+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                s.bind(("127.0.0.1", port))
+                return port
+        except OSError:
+            continue
+    return None
+
+
+class ProbeCommand(BaseCommand):
+    """WebSocket proxy with periodic ffprobe analysis of streaming audio."""
+
+    name = "probe"
+    help = (
+        "Launch a local WebSocket proxy that periodically probes "
+        "streaming audio with ffprobe while forwarding to Deepgram."
+    )
+    short_help = "Stream probe proxy"
+
+    requires_auth = True
+    requires_project = False
+    ci_friendly = False
+
+    examples = [
+        "dg debug probe",
+        "dg debug probe --port 3100",
+        "dg debug probe --probe-interval-bytes 131072",
+        "dg debug probe --probe-interval-seconds 10",
+    ]
+    agent_help = (
+        "Launch a local WebSocket proxy that sits between your application "
+        "and Deepgram's streaming API. Periodically runs ffprobe on the "
+        "accumulated audio buffer to show codec, sample rate, and channel "
+        "information alongside real-time transcripts."
+    )
+
+    def get_arguments(self) -> list[dict[str, Any]]:
+        """Get command arguments and options."""
+        return [
+            {
+                "names": ["--port", "-p"],
+                "help": "Local proxy port (default: auto-select 3100-3199)",
+                "type": int,
+                "is_option": True,
+            },
+            {
+                "names": ["--probe-interval-bytes"],
+                "help": "Probe every N bytes of audio (default: 131072)",
+                "type": int,
+                "default": 131072,
+                "is_option": True,
+            },
+            {
+                "names": ["--probe-interval-seconds"],
+                "help": "Probe every N seconds (default: 10)",
+                "type": float,
+                "default": 10.0,
+                "is_option": True,
+            },
+            {
+                "names": ["--verbose", "-v"],
+                "help": "Show per-frame details",
+                "is_flag": True,
+                "is_option": True,
+            },
+        ]
+
+    def handle(
+        self,
+        config: Config,
+        auth_manager: AuthManager,
+        client: DeepgramClient,
+        **kwargs: Any,
+    ) -> Any:
+        """Handle debug probe command execution."""
+        port = kwargs.get("port")
+        probe_interval_bytes = kwargs.get("probe_interval_bytes") or 131072
+        probe_interval_seconds = kwargs.get("probe_interval_seconds") or 10.0
+        verbose = kwargs.get("verbose", False)
+
+        # Check ffprobe availability
+        if not require_ffprobe(config):
+            return ProbeDebugResult(
+                status="error",
+                message="ffprobe is required but not found",
+            )
+
+        # Get API key
+        api_key = auth_manager.get_api_key()
+        if not api_key:
+            console.print("[red]No API key found. Run 'dg login' first.[/red]")
+            return ProbeDebugResult(
+                status="error",
+                message="No API key found",
+            )
+
+        # Find available port
+        if port is None:
+            port = _find_available_port()
+            if port is None:
+                console.print("[red]No available ports in range 3100-3199[/red]")
+                return ProbeDebugResult(
+                    status="error",
+                    message="No available ports",
+                )
+        else:
+            try:
+                with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                    s.bind(("127.0.0.1", port))
+            except OSError:
+                console.print(f"[red]Port {port} is already in use[/red]")
+                return ProbeDebugResult(
+                    status="error",
+                    message=f"Port {port} is in use",
+                    port=port,
+                )
+
+        upstream_host = "api.deepgram.com"
+
+        # Create proxy
+        proxy = ProbeProxy(
+            api_key=api_key,
+            config=config,
+            upstream_host=upstream_host,
+            probe_interval_bytes=probe_interval_bytes,
+            probe_interval_seconds=probe_interval_seconds,
+            verbose=verbose,
+        )
+
+        # Print instructions
+        console.print(
+            Panel(
+                f"[bold cyan]WebSocket Probe Proxy[/bold cyan]\n\n"
+                f"Listening on: [green]ws://localhost:{port}[/green]\n"
+                f"Upstream:     [yellow]wss://{upstream_host}[/yellow]\n"
+                f"API key:      [dim]****{api_key[-4:]}[/dim]\n\n"
+                f"Probe every:  {probe_interval_bytes:,} bytes "
+                f"or {probe_interval_seconds}s\n\n"
+                f"[bold]Point your app at the proxy URL:[/bold]\n"
+                f"  ws://localhost:{port}/v1/listen?encoding=...&sample_rate=...\n\n"
+                f"[dim]Press Ctrl+C to stop[/dim]",
+                title="Debug Probe Proxy",
+                border_style="cyan",
+            )
+        )
+
+        # Run the proxy server
+        start_time = time.time()
+        app = web.Application()
+        app.router.add_route("GET", "/{path:.*}", proxy.handle_connection)
+
+        try:
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+
+            runner = web.AppRunner(app)
+            loop.run_until_complete(runner.setup())
+
+            site = web.TCPSite(runner, "127.0.0.1", port)
+            loop.run_until_complete(site.start())
+
+            # Run until Ctrl+C
+            loop.run_forever()
+
+        except KeyboardInterrupt:
+            console.print("\n[yellow]Shutting down probe proxy...[/yellow]")
+        finally:
+            loop.run_until_complete(runner.cleanup())
+            loop.close()
+
+        duration = time.time() - start_time
+
+        console.print(f"\n[green]Probe proxy stopped after {duration:.1f}s[/green]")
+        console.print(f"Total connections: {len(proxy.connections)}")
+
+        return ProbeDebugResult(
+            status="success",
+            message="Probe proxy session completed",
+            port=port,
+            upstream_host=upstream_host,
+            connections=proxy.connections,
+            duration_seconds=duration,
+        )

deepctl_cmd_debug_probe/models.py

@@ -0,0 +1,42 @@
+"""Data models for debug probe command."""
+
+from __future__ import annotations
+
+from deepctl_core import BaseResult
+from deepctl_shared_utils.ffprobe_models import AudioProbeResult  # noqa: TC002
+from pydantic import BaseModel, Field
+
+
+class ProbeSnapshot(BaseModel):
+    """A single ffprobe snapshot taken during streaming."""
+
+    timestamp: float = 0.0
+    bytes_at_probe: int = 0
+    result: AudioProbeResult | None = None
+
+
+class ProbeConnectionStats(BaseModel):
+    """Statistics for a single probe proxy connection."""
+
+    connection_id: str
+    stream_type: str = "unknown"
+    path: str = ""
+    bytes_sent: int = 0
+    bytes_received: int = 0
+    frames_sent: int = 0
+    frames_received: int = 0
+    text_frames_sent: int = 0
+    text_frames_received: int = 0
+    duration_seconds: float | None = None
+    snapshots: list[ProbeSnapshot] = Field(default_factory=list)
+    transcripts: list[str] = Field(default_factory=list)
+    audio_buffer: bytes = Field(default=b"", exclude=True, repr=False)
+
+
+class ProbeDebugResult(BaseResult):
+    """Result from debug probe command execution."""
+
+    port: int = 0
+    upstream_host: str = ""
+    connections: list[ProbeConnectionStats] = Field(default_factory=list)
+    duration_seconds: float | None = None

deepctl_cmd_debug_probe/proxy.py

@@ -0,0 +1,278 @@
+"""WebSocket proxy with periodic ffprobe analysis."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+import uuid
+from typing import TYPE_CHECKING
+
+import aiohttp
+from aiohttp import web
+from deepctl_shared_utils import probe_buffer
+from rich.console import Console
+
+from .models import ProbeConnectionStats, ProbeSnapshot
+
+if TYPE_CHECKING:
+    from deepctl_core import Config
+
+console = Console()
+
+
+class ProbeProxy:
+    """WebSocket proxy that probes audio at configurable intervals."""
+
+    # Maximum audio buffer size (1 MB). Only the most recent bytes are kept
+    # to prevent unbounded memory growth on long-running streams.
+    MAX_BUFFER_BYTES = 1_048_576
+
+    def __init__(
+        self,
+        api_key: str,
+        config: Config | None = None,
+        upstream_host: str = "api.deepgram.com",
+        probe_interval_bytes: int = 131072,
+        probe_interval_seconds: float = 10.0,
+        verbose: bool = False,
+    ) -> None:
+        self.api_key = api_key
+        self.config = config
+        self.upstream_host = upstream_host
+        self.probe_interval_bytes = probe_interval_bytes
+        self.probe_interval_seconds = probe_interval_seconds
+        self.verbose = verbose
+        self.connections: list[ProbeConnectionStats] = []
+
+    def _detect_stream_type(self, path: str) -> str:
+        """Detect stream type from the request path."""
+        if "/v1/listen" in path:
+            return "stt"
+        elif "/v1/speak" in path:
+            return "tts"
+        elif "/agent" in path:
+            return "agent"
+        return "unknown"
+
+    async def handle_connection(self, request: web.Request) -> web.WebSocketResponse:
+        """Handle an incoming WebSocket connection."""
+        ws_client = web.WebSocketResponse()
+        await ws_client.prepare(request)
+
+        conn_id = str(uuid.uuid4())[:8]
+        path = request.path
+        query_string = request.query_string
+        stream_type = self._detect_stream_type(path)
+
+        stats = ProbeConnectionStats(
+            connection_id=conn_id,
+            stream_type=stream_type,
+            path=path,
+        )
+        self.connections.append(stats)
+
+        upstream_url = f"wss://{self.upstream_host}{path}"
+        if query_string:
+            upstream_url = f"{upstream_url}?{query_string}"
+
+        upstream_headers = {
+            "Authorization": f"Token {self.api_key}",
+        }
+
+        console.print(
+            f"\n[green]New connection[/green] [{conn_id}] "
+            f"type={stream_type} path={path}"
+        )
+
+        start_time = time.time()
+        last_probe_time = start_time
+        last_probe_bytes = 0
+
+        try:
+            async with (
+                aiohttp.ClientSession() as session,
+                session.ws_connect(
+                    upstream_url,
+                    headers=upstream_headers,
+                    timeout=aiohttp.ClientWSTimeout(ws_close=30.0),
+                ) as ws_upstream,
+            ):
+
+                async def forward_client_to_upstream() -> None:
+                    nonlocal last_probe_time, last_probe_bytes
+
+                    async for msg in ws_client:
+                        if msg.type == aiohttp.WSMsgType.BINARY:
+                            stats.bytes_sent += len(msg.data)
+                            stats.frames_sent += 1
+
+                            # Keep only the tail of the buffer to bound memory
+                            stats.audio_buffer += msg.data
+                            if len(stats.audio_buffer) > self.MAX_BUFFER_BYTES:
+                                stats.audio_buffer = stats.audio_buffer[
+                                    -self.MAX_BUFFER_BYTES :
+                                ]
+
+                            await ws_upstream.send_bytes(msg.data)
+
+                            if self.verbose:
+                                console.print(
+                                    f"  [dim]→ binary {len(msg.data)} bytes[/dim]"
+                                )
+
+                            # Check probe thresholds
+                            now = time.time()
+                            bytes_since = stats.bytes_sent - last_probe_bytes
+                            time_since = now - last_probe_time
+
+                            if (
+                                bytes_since >= self.probe_interval_bytes
+                                or time_since >= self.probe_interval_seconds
+                            ):
+                                self._run_probe_snapshot(stats, now)
+                                last_probe_time = now
+                                last_probe_bytes = stats.bytes_sent
+
+                        elif msg.type == aiohttp.WSMsgType.TEXT:
+                            stats.text_frames_sent += 1
+                            await ws_upstream.send_str(msg.data)
+                        elif msg.type in (
+                            aiohttp.WSMsgType.CLOSE,
+                            aiohttp.WSMsgType.ERROR,
+                        ):
+                            break
+
+                async def forward_upstream_to_client() -> None:
+                    async for msg in ws_upstream:
+                        if ws_client.closed:
+                            break
+
+                        if msg.type == aiohttp.WSMsgType.BINARY:
+                            stats.bytes_received += len(msg.data)
+                            stats.frames_received += 1
+                            await ws_client.send_bytes(msg.data)
+                        elif msg.type == aiohttp.WSMsgType.TEXT:
+                            stats.text_frames_received += 1
+                            await ws_client.send_str(msg.data)
+
+                            # Parse transcript from Deepgram response
+                            self._parse_transcript(msg.data, stats)
+                        elif msg.type in (
+                            aiohttp.WSMsgType.CLOSE,
+                            aiohttp.WSMsgType.ERROR,
+                        ):
+                            break
+
+                # Run both forwarders concurrently. If one fails,
+                # cancel the other instead of letting it dangle.
+                task_c2u = asyncio.ensure_future(forward_client_to_upstream())
+                task_u2c = asyncio.ensure_future(forward_upstream_to_client())
+                try:
+                    await asyncio.gather(task_c2u, task_u2c)
+                except Exception:
+                    pass
+                finally:
+                    for task in (task_c2u, task_u2c):
+                        if not task.done():
+                            task.cancel()
+                    # Suppress CancelledError from the cancelled task
+                    await asyncio.gather(task_c2u, task_u2c, return_exceptions=True)
+
+        except aiohttp.ClientError as e:
+            console.print(f"[red]Upstream connection failed[/red] [{conn_id}]: {e}")
+        except Exception as e:
+            console.print(f"[red]Connection error[/red] [{conn_id}]: {e}")
+        finally:
+            stats.duration_seconds = time.time() - start_time
+
+            # Final probe
+            if stats.audio_buffer:
+                console.print(f"\n[bold]Final probe[/bold] [{conn_id}]:")
+                self._run_probe_snapshot(stats, time.time())
+
+            self._print_connection_summary(stats)
+
+            if not ws_client.closed:
+                await ws_client.close()
+
+        return ws_client
+
+    def _run_probe_snapshot(
+        self, stats: ProbeConnectionStats, timestamp: float
+    ) -> None:
+        """Run a probe snapshot on the accumulated audio buffer."""
+        result = probe_buffer(stats.audio_buffer, "probe", self.config)
+        snapshot = ProbeSnapshot(
+            timestamp=timestamp,
+            bytes_at_probe=stats.bytes_sent,
+            result=result,
+        )
+        stats.snapshots.append(snapshot)
+
+        if result and result.streams:
+            stream = result.streams[0]
+            parts = []
+            if stream.codec_name:
+                parts.append(f"codec={stream.codec_name}")
+            if stream.sample_rate:
+                parts.append(f"rate={stream.sample_rate}Hz")
+            if stream.channels is not None:
+                parts.append(f"ch={stream.channels}")
+            info = " ".join(parts)
+            console.print(
+                f"  [cyan]probe[/cyan] [{stats.connection_id}] "
+                f"@{stats.bytes_sent:,}B: {info}"
+            )
+        elif result and result.format:
+            console.print(
+                f"  [cyan]probe[/cyan] [{stats.connection_id}] "
+                f"@{stats.bytes_sent:,}B: format={result.format.format_name}"
+            )
+        else:
+            console.print(
+                f"  [dim]probe[/dim] [{stats.connection_id}] "
+                f"@{stats.bytes_sent:,}B: could not determine format"
+            )
+
+    def _parse_transcript(self, text: str, stats: ProbeConnectionStats) -> None:
+        """Parse Deepgram transcript from upstream TEXT frame."""
+        try:
+            data = json.loads(text)
+            # Deepgram STT responses have channel.alternatives[].transcript
+            channel = data.get("channel", {})
+            alternatives = channel.get("alternatives", [])
+            if alternatives:
+                transcript = alternatives[0].get("transcript", "")
+                is_final = data.get("is_final", False)
+                if transcript and is_final:
+                    stats.transcripts.append(transcript)
+                    console.print(
+                        f"  [green]transcript[/green] [{stats.connection_id}]: "
+                        f"{transcript[:120]}"
+                    )
+        except (json.JSONDecodeError, AttributeError):
+            pass
+
+    def _print_connection_summary(self, stats: ProbeConnectionStats) -> None:
+        """Print summary for a completed connection."""
+        console.print(f"\n[blue]Connection closed[/blue] [{stats.connection_id}]")
+        console.print(f"  Type: {stats.stream_type}")
+        console.print(
+            f"  Duration: {stats.duration_seconds:.1f}s"
+            if stats.duration_seconds
+            else "  Duration: <1s"
+        )
+        console.print(
+            f"  Sent: {stats.bytes_sent:,} bytes "
+            f"({stats.frames_sent} binary, "
+            f"{stats.text_frames_sent} text frames)"
+        )
+        console.print(
+            f"  Received: {stats.bytes_received:,} bytes "
+            f"({stats.frames_received} binary, "
+            f"{stats.text_frames_received} text frames)"
+        )
+        console.print(f"  Probe snapshots: {len(stats.snapshots)}")
+        if stats.transcripts:
+            console.print(f"  Transcripts received: {len(stats.transcripts)}")

deepctl_cmd_debug_probe-0.0.2.dist-info/METADATA

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: deepctl-cmd-debug-probe
+Version: 0.0.2
+Summary: Debug probe subcommand for deepctl — live ffprobe analysis during streaming
+Author-email: Deepgram <devrel@deepgram.com>
+Maintainer-email: Deepgram <devrel@deepgram.com>
+License-Expression: MIT
+Keywords: deepgram,cli,debug,probe,ffprobe,websocket
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: deepctl-core>=0.1.10
+Requires-Dist: deepctl-shared-utils>=0.1.10
+Requires-Dist: click>=8.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: aiohttp>=3.8.0
+
+# deepctl-cmd-debug-probe
+
+> Part of [deepctl](https://github.com/deepgram/cli) — Official Deepgram CLI
+
+Debug probe subcommand for deepctl — live ffprobe analysis during streaming
+
+This is a subcommand of `deepctl debug`.
+
+## Installation
+
+This package is included with deepctl and does not need to be installed separately.
+
+### Install deepctl
+
+```bash
+# Install with pip
+pip install deepctl
+
+# Or install with uv
+uv tool install deepctl
+
+# Or install with pipx
+pipx install deepctl
+
+# Or run without installing
+uvx deepctl --help
+pipx run deepctl --help
+```
+
+## Commands
+
+| Command | Entry Point |
+|---------|-------------|
+| `deepctl debug probe` | `deepctl_cmd_debug_probe.command:ProbeCommand` |
+
+## Dependencies
+
+- `click>=8.0.0`
+- `rich>=13.0.0`
+- `pydantic>=2.0.0`
+- `aiohttp>=3.8.0`
+
+## License
+
+MIT — see [LICENSE](../../LICENSE)

deepctl_cmd_debug_probe-0.0.2.dist-info/RECORD

@@ -0,0 +1,9 @@
+deepctl_cmd_debug_probe/__init__.py,sha256=IBujDn4L6LmDvrjzs7zMHY2G9rfQRqL_nSHxACxPBkY,148
+deepctl_cmd_debug_probe/command.py,sha256=3aZZBse-7mxthPLVzTbxzK4YpPVHYaYLOkz_LrqLSbk,6924
+deepctl_cmd_debug_probe/models.py,sha256=APtFtLPbzQWvEC2_TNdDdpk9QoTrTLibFWt-qE5FHn8,1261
+deepctl_cmd_debug_probe/proxy.py,sha256=0aEbTk8ewR4UF15R1p3bpoGEBLRmwvFcU6zMrebQC1k,10738
+deepctl_cmd_debug_probe-0.0.2.dist-info/METADATA,sha256=6_hxBRC8ms8ArgaIb7kmjCnHUphIGGfJjKaKpNhWoyE,1723
+deepctl_cmd_debug_probe-0.0.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+deepctl_cmd_debug_probe-0.0.2.dist-info/entry_points.txt,sha256=KtP7bpTfgLoXR65MjEztjfb7nH_KSvZ-jzCbQG2zcGQ,81
+deepctl_cmd_debug_probe-0.0.2.dist-info/top_level.txt,sha256=zlC3OL8txzyhhvPgBISuWkMK6IN9w-HlqRfXo-Z7G9o,24
+deepctl_cmd_debug_probe-0.0.2.dist-info/RECORD,,

deepctl_cmd_debug_probe-0.0.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

deepctl_cmd_debug_probe-0.0.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[deepctl.subcommands.debug]
+probe = deepctl_cmd_debug_probe.command:ProbeCommand

deepctl_cmd_debug_probe-0.0.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+deepctl_cmd_debug_probe