deepctl-core 0.2.13__tar.gz → 0.2.16__tar.gz

{deepctl_core-0.2.13 → deepctl_core-0.2.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepctl-core
-Version: 0.2.13
+Version: 0.2.16
 Summary: Core components for deepctl
 Author-email: Deepgram <devrel@deepgram.com>
 Maintainer-email: Deepgram <devrel@deepgram.com>
@@ -16,7 +16,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: click>=8.0.0
-Requires-Dist: deepgram-sdk>=6.0.0rc2
+Requires-Dist: deepgram-sdk<8,>=7.7.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: httpx>=0.24.0
@@ -63,7 +63,7 @@ pipx run deepctl --help
 ## Dependencies
 
 - `click>=8.0.0`
-- `deepgram-sdk>=6.0.0rc2`
+- `deepgram-sdk>=7.7.0,<8`
 - `pydantic>=2.0.0`
 - `rich>=13.0.0`
 - `httpx>=0.24.0`

{deepctl_core-0.2.13 → deepctl_core-0.2.16}/README.md

@@ -30,7 +30,7 @@ pipx run deepctl --help
 ## Dependencies
 
 - `click>=8.0.0`
-- `deepgram-sdk>=6.0.0rc2`
+- `deepgram-sdk>=7.7.0,<8`
 - `pydantic>=2.0.0`
 - `rich>=13.0.0`
 - `httpx>=0.24.0`

{deepctl_core-0.2.13 → deepctl_core-0.2.16}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-core"
-version = "0.2.13" # x-release-please-version
+version = "0.2.16" # x-release-please-version
 description = "Core components for deepctl"
 readme = "README.md"
 license = "MIT"
@@ -23,7 +23,7 @@ keywords = ["deepgram", "core", "auth", "config", "client"]
 requires-python = ">=3.10"
 dependencies = [
     "click>=8.0.0",
-    "deepgram-sdk>=6.0.0rc2",
+    "deepgram-sdk>=7.7.0,<8",
     "pydantic>=2.0.0",
     "rich>=13.0.0",
     "httpx>=0.24.0",

{deepctl_core-0.2.13 → deepctl_core-0.2.16}/src/deepctl_core/__init__.py

@@ -16,6 +16,7 @@ from .output import (
     OutputFormatter,
     get_console,
     get_output_format,
+    get_status_console,
     is_agentic,
     print_error,
     print_info,
@@ -50,6 +51,8 @@ __all__ = [
     "TimingContext",
     "enable_timing",
     "get_console",
+    "get_output_format",
+    "get_status_console",
     "get_timing_summary",
     "is_agentic",
     "is_timing_enabled",

{deepctl_core-0.2.13 → deepctl_core-0.2.16}/src/deepctl_core/auth.py

@@ -12,6 +12,7 @@ from pydantic import BaseModel
 from rich.console import Console
 from rich.progress import Progress, SpinnerColumn, TextColumn
 
+from .client import _split_base_url
 from .config import Config
 from .models import ProfileInfo, ProfilesResult
 
@@ -273,8 +274,14 @@ class AuthManager:
                 "Content-Type": "application/json",
             }
 
+            # Verify against the configured base URL (not hardcoded prod), so a
+            # custom base (e.g. staging) validates its own keys correctly.
+            # Preserve the input scheme so a plaintext endpoint isn't forced
+            # onto TLS.
+            base = self.config.get_profile().base_url or "https://api.deepgram.com"
+            rest_scheme, _, host = _split_base_url(base)
             response = self.client.get(
-                "https://api.deepgram.com/v1/projects",
+                f"{rest_scheme}://{host}/v1/projects",
                 headers=headers,
             )
 

{deepctl_core-0.2.13 → deepctl_core-0.2.16}/src/deepctl_core/base_command.py

@@ -29,6 +29,19 @@ class BaseCommand(ABC):
     requires_project: bool = False
     ci_friendly: bool = True
 
+    # Result status -> process exit code, per the contract published in
+    # llms-full.txt: 0 = success, 1 = error, 2 = user interrupt. A command that
+    # reports failure must not exit 0 -- scripts and CI branch on the exit code,
+    # not on the "status" field inside the payload. "cancelled" is 2 rather than
+    # the shell's 130 to match that contract and main.py's own KeyboardInterrupt
+    # handler; `dg mcp` in particular returns cancelled straight out of its
+    # KeyboardInterrupt path. Any status not listed here exits 0
+    # (success, succeeded, info, dry_run, warning).
+    EXIT_CODES: ClassVar[dict[str, int]] = {
+        "error": 1,
+        "cancelled": 2,
+    }
+
     # Agent-oriented metadata
     examples: ClassVar[list[str]] = []
     agent_help: str = ""
@@ -56,7 +69,10 @@ class BaseCommand(ABC):
                     config = Config()
 
                 # Extract explicit credentials from kwargs if provided
-                explicit_api_key = kwargs.get("api_key")
+                # (or from the global --api-key option stored on ctx.obj)
+                explicit_api_key = kwargs.get("api_key") or (
+                    ctx.obj.get("api_key") if ctx.obj else None
+                )
                 explicit_project_id = kwargs.get("project_id")
 
                 # Create auth manager with explicit credentials
@@ -144,6 +160,23 @@ class BaseCommand(ABC):
                     stderr_console.print_exception()
                 raise click.ClickException(str(e))
 
+            # Payload is already on stdout; now make the exit code agree with it.
+            exit_code = self.exit_code_for(result)
+            if exit_code:
+                raise SystemExit(exit_code)
+
+    def exit_code_for(self, result: Any) -> int:
+        """Map a command result to a process exit code.
+
+        Args:
+            result: Command result (may be None)
+
+        Returns:
+            Exit code for this result's status; 0 when it reported no failure
+        """
+        status = str(getattr(result, "status", "") or "")
+        return self.EXIT_CODES.get(status, 0)
+
     def is_guided(self, ctx: click.Context) -> bool:
         """True only when the user invoked this command with no input at all.
 
@@ -282,9 +315,25 @@ class BaseCommand(ABC):
             elif output_format == "csv":
                 self._output_csv(result)
             else:
-                console.print(f"[red]Unknown output format:[/red] {output_format}")
+                # Diagnostics belong on stderr even here, or the complaint about
+                # the format corrupts the payload we fall back to.
+                stderr_console.print(
+                    f"[red]Unknown output format:[/red] {output_format}"
+                )
                 self._output_json(result)
 
+    def _write_payload(self, text: str) -> None:
+        """Write already-serialised machine-readable text to stdout verbatim.
+
+        Rich's default print would treat square brackets as style markup and
+        silently delete them, so a key comment of "[ci] runner" would lose the
+        "[ci]". It would also hard-wrap at the console width, injecting newlines
+        into the middle of a value. Both corrupt the payload, so markup,
+        highlighting and wrapping are all off. Routed through `console` rather
+        than `sys.stdout` so `--quiet` still suppresses output.
+        """
+        console.print(text, markup=False, highlight=False, soft_wrap=True)
+
     def _output_json(self, result: Any) -> None:
         """Output result as JSON."""
         import json
@@ -307,9 +356,11 @@ class BaseCommand(ABC):
         import yaml
 
         if isinstance(result, dict | list):
-            console.print(yaml.dump(result, default_flow_style=False))
+            self._write_payload(yaml.dump(result, default_flow_style=False))
         else:
-            console.print(yaml.dump({"result": str(result)}, default_flow_style=False))
+            self._write_payload(
+                yaml.dump({"result": str(result)}, default_flow_style=False)
+            )
 
     def _output_table(self, result: Any) -> None:
         """Output result as table."""
@@ -356,7 +407,7 @@ class BaseCommand(ABC):
             dict_writer = csv.DictWriter(output, fieldnames=result[0].keys())
             dict_writer.writeheader()
             dict_writer.writerows(result)
-            console.print(output.getvalue())
+            self._write_payload(output.getvalue())
 
         elif isinstance(result, dict):
             # Dictionary
@@ -365,7 +416,7 @@ class BaseCommand(ABC):
             writer.writerow(["Key", "Value"])
             for key, value in result.items():
                 writer.writerow([key, value])
-            console.print(output.getvalue())
+            self._write_payload(output.getvalue())
 
         else:
             # Fallback to JSON

{deepctl_core-0.2.13 → deepctl_core-0.2.16}/src/deepctl_core/client.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import re
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, cast
 
@@ -20,6 +21,22 @@ if TYPE_CHECKING:
 console = Console()
 
 
+def _split_base_url(base_url: str) -> tuple[str, str, str]:
+    """Split a base URL into (rest_scheme, ws_scheme, host).
+
+    Preserves the transport implied by the input scheme so a plaintext
+    endpoint is not forced onto TLS: an ``http://`` base maps to ``http`` for
+    REST and ``ws`` for WebSocket; anything else (including a bare host) maps
+    to ``https``/``wss``. The host is returned without scheme or trailing slash.
+    """
+    match = re.match(r"^([a-z]+)://", base_url)
+    scheme = match.group(1) if match else "https"
+    host = re.sub(r"^[a-z]+://", "", base_url).rstrip("/")
+    if scheme in ("http", "ws"):
+        return "http", "ws", host
+    return "https", "wss", host
+
+
 class DeepgramClient:
     """Wrapper around Deepgram SDK with authentication integration."""
 
@@ -64,10 +81,18 @@ class DeepgramClient:
                 current_profile.base_url
                 and current_profile.base_url != "https://api.deepgram.com"
             ):
+                # Derive both the REST and WebSocket endpoints from the
+                # configured base URL, so a custom base works for batch REST
+                # *and* streaming. Preserve the transport implied by the input
+                # scheme (http→ws, https→wss) so a plaintext local/staging
+                # endpoint isn't forced onto TLS. agent_rest is required by the
+                # SDK environment.
+                rest_scheme, ws_scheme, host = _split_base_url(current_profile.base_url)
                 kwargs["environment"] = DeepgramClientEnvironment(
-                    base=current_profile.base_url,
-                    production=current_profile.base_url,
-                    agent=current_profile.base_url,
+                    base=f"{rest_scheme}://{host}",
+                    production=f"{ws_scheme}://{host}",
+                    agent=f"{ws_scheme}://{host}",
+                    agent_rest=f"{rest_scheme}://{host}",
                 )
 
             client = DGClient(**kwargs)
@@ -158,6 +183,49 @@ class DeepgramClient:
         except Exception as e:
             raise ApiError(body=f"Text-to-speech failed: {e}")
 
+    def speak_text_stream(
+        self,
+        text: str,
+        model: str,
+        encoding: str | None = None,
+        sample_rate: float | None = None,
+        speed: float | None = None,
+        expressivity: int | None = None,
+    ) -> Iterator[bytes]:
+        """Stream TTS audio over the Flux v2 WebSocket (speak.v2.connect).
+
+        Yields raw audio chunks as they arrive. The streaming transport emits
+        raw (non-containerized) audio, so only linear16/mulaw/alaw encodings
+        apply and sample_rate is sent as the string the streaming API expects.
+
+        ``speed`` (0.85-1.15) and beta ``expressivity`` (-2..2, default 0) are
+        Flux connect query parameters; they are only sent when set.
+        """
+        from deepgram.speak.v2.types.speak_v2speak import SpeakV2Speak
+
+        connect_kwargs: dict[str, Any] = {"model": model}
+        if encoding:
+            connect_kwargs["encoding"] = encoding
+        if sample_rate:
+            connect_kwargs["sample_rate"] = str(int(sample_rate))
+        if speed is not None:
+            connect_kwargs["speed"] = speed
+        if expressivity is not None:
+            connect_kwargs["expressivity"] = expressivity
+
+        try:
+            with self.client.speak.v2.connect(**connect_kwargs) as conn:
+                conn.send_speak(SpeakV2Speak(type="Speak", text=text))
+                conn.send_flush()
+                conn.send_close()
+                for message in conn:
+                    # Audio arrives as raw bytes; control messages are parsed
+                    # objects, which we skip here.
+                    if isinstance(message, bytes):
+                        yield message
+        except Exception as e:
+            raise ApiError(body=f"Text-to-speech streaming failed: {e}")
+
     # ── Text Intelligence (Read) ───────────────────────────────────
 
     def analyze_text(

{deepctl_core-0.2.13 → deepctl_core-0.2.16}/src/deepctl_core/output.py

@@ -505,3 +505,19 @@ def get_console() -> Console:
         Console instance
     """
     return console
+
+
+def get_status_console() -> Console:
+    """Get the console for status/progress chrome.
+
+    Always writes to stderr, so anything printed through it can never corrupt
+    the machine-readable payload a command writes to stdout. Commands should
+    use this rather than declaring their own ``Console(stderr=True)`` — a
+    per-command console silently misses the agentic no-color settings, and a
+    command that reaches for a bare ``Console()`` reintroduces the stdout
+    pollution this exists to prevent.
+
+    Returns:
+        Console instance writing to stderr
+    """
+    return stderr_console

{deepctl_core-0.2.13 → deepctl_core-0.2.16}/src/deepctl_core/skill_generator.py

@@ -417,7 +417,8 @@ def render_developer_guide(
     lines.append("## Text-to-Speech (TTS)")
     lines.append("")
     lines.append(
-        "Generate natural-sounding speech from text using Deepgram's Aura voices."
+        "Generate natural-sounding speech from text using Deepgram's Aura and "
+        "Flux voices."
     )
     lines.append("")
     lines.append("### Models")
@@ -426,47 +427,84 @@ def render_developer_guide(
         "- **Aura-2** — Latest generation. High quality, low latency, many voices."
     )
     lines.append("- **Aura** — Previous generation. Solid quality and performance.")
+    lines.append(
+        "- **Flux** — Conversational TTS on the Speak v2 WebSocket API "
+        "(streaming, turn-based). Voices like `flux-alexis-en`."
+    )
     lines.append("")
     lines.append("### Popular Voices")
     lines.append("")
-    lines.append("Voices follow the naming pattern `aura-2-{name}-en`. Examples:")
+    lines.append("Aura voices follow `aura-2-{name}-en`. Examples:")
     lines.append("- `aura-2-andromeda-en`, `aura-2-arcas-en`, `aura-2-atlas-en`")
     lines.append("- `aura-2-luna-en`, `aura-2-stella-en`, `aura-2-helios-en`")
     lines.append("")
+    lines.append(
+        "Flux (Speak v2) voices follow `flux-{name}-en` (English at launch), "
+        "e.g. `flux-alexis-en`."
+    )
+    lines.append("")
     lines.append("Full voice list: <https://developers.deepgram.com/docs/tts-models>")
     lines.append("")
-    lines.append("### TTS Example (Python)")
+    lines.append("### Aura TTS — Speak v1, batch REST (Python)")
     lines.append("")
     lines.append("```python")
-    lines.append("from deepgram import DeepgramClient, SpeakOptions")
+    lines.append("from deepgram import DeepgramClient")
     lines.append("")
-    lines.append('dg = DeepgramClient("DEEPGRAM_API_KEY")')
+    lines.append('client = DeepgramClient(api_key="DEEPGRAM_API_KEY")')
     lines.append("")
-    lines.append("options = SpeakOptions(")
-    lines.append('    model="aura-2-andromeda-en"')
+    lines.append("audio = client.speak.v1.audio.generate(")
+    lines.append('    text="Hello from Deepgram!",')
+    lines.append('    model="aura-2-andromeda-en",')
+    lines.append('    encoding="mp3",')
     lines.append(")")
+    lines.append('with open("output.mp3", "wb") as f:')
+    lines.append("    for chunk in audio:")
+    lines.append("        f.write(chunk)")
+    lines.append("```")
     lines.append("")
-    lines.append('response = dg.speak.rest.v("1").save(')
-    lines.append('    "output.mp3",')
-    lines.append('    {"text": "Hello from Deepgram!"},')
-    lines.append("    options,")
-    lines.append(")")
+    lines.append("### Flux TTS — Speak v2, WebSocket streaming (Python)")
+    lines.append("")
+    lines.append(
+        "`expressivity` is beta and defaults to `0` (nominal delivery) when omitted."
+    )
+    lines.append("")
+    lines.append("```python")
+    lines.append("from deepgram import DeepgramClient")
+    lines.append("from deepgram.speak.v2.types.speak_v2speak import SpeakV2Speak")
+    lines.append("")
+    lines.append('client = DeepgramClient(api_key="DEEPGRAM_API_KEY")')
+    lines.append("")
+    lines.append("with client.speak.v2.connect(")
+    lines.append('    model="flux-alexis-en",')
+    lines.append('    encoding="linear16",')
+    lines.append('    sample_rate="24000",')
+    lines.append("    speed=1.0,  # 0.85–1.15 in 0.05 steps (optional)")
+    lines.append("    expressivity=0,  # beta; -2..2, default 0 = nominal (optional)")
+    lines.append(") as conn:")
+    lines.append(
+        '    conn.send_speak(SpeakV2Speak(type="Speak", text="Hello from Flux!"))'
+    )
+    lines.append("    conn.send_flush()")
+    lines.append("    conn.send_close()")
+    lines.append('    with open("output.raw", "wb") as f:')
+    lines.append("        for message in conn:")
+    lines.append("            if isinstance(message, bytes):")
+    lines.append("                f.write(message)  # raw linear16 PCM, 24kHz mono")
     lines.append("```")
     lines.append("")
-    lines.append("### TTS Example (JavaScript)")
+    lines.append("### Aura TTS — Speak v1 (JavaScript)")
     lines.append("")
     lines.append("```javascript")
     lines.append('import { createClient } from "@deepgram/sdk";')
     lines.append("")
-    lines.append('const dg = createClient("DEEPGRAM_API_KEY");')
-    lines.append("")
-    lines.append("const response = await dg.speak.request(")
-    lines.append('  { text: "Hello from Deepgram!" },')
-    lines.append('  { model: "aura-2-andromeda-en" }')
-    lines.append(");")
+    lines.append('const client = createClient("DEEPGRAM_API_KEY");')
     lines.append("")
-    lines.append("const stream = await response.getStream();")
-    lines.append("// Write stream to file or audio output")
+    lines.append("const response = await client.speak.v1.audio.generate({")
+    lines.append('  text: "Hello from Deepgram!",')
+    lines.append('  model: "aura-2-andromeda-en",')
+    lines.append("});")
+    lines.append("const buffer = await response.arrayBuffer();")
+    lines.append("// Write buffer to a file or audio output")
     lines.append("```")
     lines.append("")
 

{deepctl_core-0.2.13 → deepctl_core-0.2.16}/src/deepctl_core.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepctl-core
-Version: 0.2.13
+Version: 0.2.16
 Summary: Core components for deepctl
 Author-email: Deepgram <devrel@deepgram.com>
 Maintainer-email: Deepgram <devrel@deepgram.com>
@@ -16,7 +16,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: click>=8.0.0
-Requires-Dist: deepgram-sdk>=6.0.0rc2
+Requires-Dist: deepgram-sdk<8,>=7.7.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: httpx>=0.24.0
@@ -63,7 +63,7 @@ pipx run deepctl --help
 ## Dependencies
 
 - `click>=8.0.0`
-- `deepgram-sdk>=6.0.0rc2`
+- `deepgram-sdk>=7.7.0,<8`
 - `pydantic>=2.0.0`
 - `rich>=13.0.0`
 - `httpx>=0.24.0`

{deepctl_core-0.2.13 → deepctl_core-0.2.16}/src/deepctl_core.egg-info/requires.txt

@@ -1,5 +1,5 @@
 click>=8.0.0
-deepgram-sdk>=6.0.0rc2
+deepgram-sdk<8,>=7.7.0
 pydantic>=2.0.0
 rich>=13.0.0
 httpx>=0.24.0