duhub-cli 0.1.0__py3-none-any.whl

du_cli/__init__.py

@@ -0,0 +1 @@
+"""duhub CLI — external developer client for DUhub."""

du_cli/client.py

@@ -0,0 +1,65 @@
+"""Single httpx wrapper: auth headers, error hints, timeout."""
+from __future__ import annotations
+
+import contextlib
+
+import httpx
+
+TIMEOUT = 300.0
+CONNECT_TIMEOUT = 10.0
+MAX_UPLOAD_BYTES = 30 * 1024 * 1024
+
+class CliError(Exception):
+    def __init__(self, status: int, detail: str, hint: str):
+        super().__init__(detail)
+        self.status = status
+        self.detail = detail
+        self.hint = hint
+
+def make_client() -> httpx.Client:
+    # Long read timeout for audio jobs, short connect timeout for bad hosts.
+    return httpx.Client(timeout=httpx.Timeout(TIMEOUT, connect=CONNECT_TIMEOUT))
+
+@contextlib.contextmanager
+def api_client():
+    """Yield an httpx client; transport failures become CliError (no tracebacks)."""
+    try:
+        with make_client() as c:
+            yield c
+    except httpx.RequestError as e:
+        raise CliError(
+            502,
+            f"cannot reach server: {e}",
+            "check base URL and try `duhub health --detailed`",
+        ) from e
+
+def auth_headers(api_key: str, idempotency_key: str | None = None) -> dict[str, str]:
+    h = {"X-API-Key": api_key}
+    if idempotency_key:
+        h["Idempotency-Key"] = idempotency_key
+    return h
+
+def error_hint(status: int, detail: str, path: str = "") -> str:
+    d = (detail or "").lower()
+    if status == 401:
+        return "invalid key — run `duhub configure`, copy from dashboard API Keys"
+    if status == 402 or "insufficient_balance" in d:
+        return "insufficient balance — top-up via dashboard Wallet"
+    if status == 403:
+        return "organization pending review — contact org admin"
+    if status == 413:
+        return "file exceeds 30 MB limit — compress or split audio"
+    if status == 503:
+        return "server busy (saturated) — retry after Retry-After seconds"
+    if status == 502:
+        return "backend unreachable — try `duhub health --detailed`"
+    if status == 404:
+        return "not found — check base URL and gateway version"
+    return detail or f"HTTP {status}"
+
+def raise_for_api(status: int, body: str, path: str = "") -> None:
+    if 200 <= status < 300:
+        return
+    detail = body[:500] if body else f"HTTP {status}"
+    # try to keep gateway JSON detail readable
+    raise CliError(status, detail, error_hint(status, detail, path))

du_cli/config.py

@@ -0,0 +1,67 @@
+"""Config load/save: env > ~/.config/du/config.toml > defaults."""
+from __future__ import annotations
+
+import os
+import tomllib
+from pathlib import Path
+
+DEFAULT_BASE_URL = "https://du-api.dev.umuganda.digital"
+CONFIG_PATH = Path.home() / ".config" / "du" / "config.toml"
+
+def _read_file(path: Path) -> dict[str, str]:
+    try:
+        with path.open("rb") as fh:
+            data = tomllib.load(fh)
+    except (FileNotFoundError, tomllib.TOMLDecodeError, UnicodeDecodeError, OSError):
+        return {}
+    out: dict[str, str] = {}
+    if isinstance(data.get("base_url"), str):
+        out["base_url"] = data["base_url"]
+    if isinstance(data.get("api_key"), str):
+        out["api_key"] = data["api_key"]
+    return out
+
+def load_config(base_url_override: str | None = None, api_key_override: str | None = None) -> dict[str, str]:
+    filed = _read_file(CONFIG_PATH)
+    base = base_url_override if base_url_override is not None else os.environ.get("DU_BASE_URL", filed.get("base_url", DEFAULT_BASE_URL))
+    key = api_key_override if api_key_override is not None else os.environ.get("DU_API_KEY", filed.get("api_key", ""))
+    return {"base_url": base.strip().rstrip("/"), "api_key": key.strip()}
+
+def _q(v: str) -> str:
+    escaped = (
+        v.replace("\\", "\\\\")
+        .replace('"', '\\"')
+        .replace("\n", "\\n")
+        .replace("\r", "\\r")
+        .replace("\t", "\\t")
+    )
+    return '"' + escaped + '"'
+
+def save_config(base_url: str | None, api_key: str | None) -> Path:
+    CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    prev = _read_file(CONFIG_PATH)
+    if base_url is not None:
+        prev["base_url"] = base_url.strip().rstrip("/")
+    if api_key is not None:
+        prev["api_key"] = api_key.strip()
+    lines = []
+    if "base_url" in prev:
+        lines.append(f"base_url = {_q(prev['base_url'])}")
+    if "api_key" in prev:
+        lines.append(f"api_key = {_q(prev['api_key'])}")
+    text = "\n".join(lines) + ("\n" if lines else "")
+    fd = os.open(CONFIG_PATH, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    if hasattr(os, "fchmod"):
+        try:
+            os.fchmod(fd, 0o600)  # tighten before the key is written
+        except OSError:
+            pass
+    with os.fdopen(fd, "w", encoding="utf-8") as fh:
+        fh.write(text)
+    return CONFIG_PATH
+
+def clear_config() -> None:
+    try:
+        CONFIG_PATH.unlink()
+    except FileNotFoundError:
+        pass

du_cli/main.py

@@ -0,0 +1,269 @@
+"""duhub CLI entrypoint: configure, health, stt, tts, mt, diarize."""
+from __future__ import annotations
+
+import contextlib
+from pathlib import Path as _Path
+
+import typer
+
+from du_cli import config, output
+from du_cli.client import (
+    MAX_UPLOAD_BYTES,
+    CliError,
+    api_client,
+    auth_headers,
+    raise_for_api,
+)
+from du_cli.output import render_segments as _render_segments
+
+__version__ = "0.1.0"
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"duhub {__version__}")
+        raise typer.Exit()
+
+app = typer.Typer(
+    no_args_is_help=True,
+    add_completion=False,
+    help="DUhub CLI — STT, TTS, MT and diarization over your API key.",
+    epilog="Keys live on the dashboard under API Keys; billing per second (audio) or word (text).",
+)
+
+@app.callback()
+def _root(
+    version: bool = typer.Option(
+        False, "--version", callback=_version_callback, is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
+    pass
+
+def _cfg(base_url: str | None, api_key: str | None) -> dict[str, str]:
+    return config.load_config(base_url, api_key)
+
+@contextlib.contextmanager
+def _api(cfg: dict[str, str], json_out: bool):
+    """Authed client; missing key, transport, or HTTP errors become exit(1)."""
+    try:
+        if not cfg["api_key"]:
+            raise CliError(401, "missing API key", "run `duhub configure --api-key KEY`")
+        with api_client() as c:
+            yield c
+    except CliError as e:
+        output.print_err(e.detail, e.hint, json_out)
+        raise typer.Exit(1)
+
+def _audio_path(file: str, json_out: bool) -> _Path:
+    """Validate an upload path; map filesystem errors to a clean CLI error."""
+    p = _Path(file)
+    try:
+        if not p.exists():
+            output.print_err(f"file not found: {file}", "check the path", json_out)
+            raise typer.Exit(1)
+        if not p.is_file():
+            output.print_err(f"not a file: {file}", "pass an audio file path", json_out)
+            raise typer.Exit(1)
+        if p.stat().st_size > MAX_UPLOAD_BYTES:
+            output.print_err("file exceeds 30 MB", "compress or split audio", json_out)
+            raise typer.Exit(1)
+    except OSError as e:
+        output.print_err(f"cannot read {file}: {e}", "check the path and permissions", json_out)
+        raise typer.Exit(1)
+    return p
+
+def _open_audio(p: _Path, json_out: bool):
+    """Open an upload file, turning permission errors into a clean CLI error."""
+    try:
+        return p.open("rb")
+    except OSError as e:
+        output.print_err(f"cannot read {p}: {e}", "check the path and permissions", json_out)
+        raise typer.Exit(1)
+
+def _check_output(o: str | None, json_out: bool) -> None:
+    if o:
+        output.check_output_path(o, json_out)
+
+@app.command()
+def configure(
+    base_url: str | None = typer.Option(None, "--base-url"),
+    api_key: str | None = typer.Option(None, "--api-key"),
+    reset: bool = typer.Option(False, "--reset"),
+) -> None:
+    if reset:
+        try:
+            config.clear_config()
+        except OSError as e:
+            output.print_err(f"cannot remove {config.CONFIG_PATH}: {e}", "check permissions", False)
+            raise typer.Exit(1)
+        typer.echo("cleared")
+        return
+    if not base_url and not api_key:
+        cur = config.load_config()
+        typer.echo(f"base_url={cur['base_url']}")
+        typer.echo("api_key=" + ("set" if cur["api_key"] else "missing"))
+        return
+    try:
+        p = config.save_config(base_url, api_key)
+    except OSError as e:
+        output.print_err(f"cannot write {config.CONFIG_PATH}: {e}", "check permissions", False)
+        raise typer.Exit(1)
+    typer.echo(f"saved {p}")
+
+@app.command()
+def health(
+    detailed: bool = typer.Option(False, "--detailed"),
+    json_out: bool = typer.Option(False, "--json", help="Machine-readable single-JSON output."),
+    base_url: str | None = typer.Option(None, "--base-url"),
+    api_key: str | None = typer.Option(None, "--api-key"),
+) -> None:
+    cfg = _cfg(base_url, api_key)
+    path = "/health/detailed" if detailed else "/health"
+    try:
+        headers = auth_headers(cfg["api_key"]) if cfg["api_key"] else {}
+        with api_client() as c:
+            r = c.get(cfg["base_url"] + path, headers=headers)
+        raise_for_api(r.status_code, r.text, path)
+        output.present(
+            r.text,
+            {"units": "", "cache": "", "request_id": r.headers.get("x-request-id", "")},
+            json_out, None,
+        )
+    except CliError as e:
+        output.print_err(e.detail, e.hint, json_out)
+        raise typer.Exit(1)
+
+@app.command()
+def stt(
+    file: str = typer.Argument(..., help="Audio file (wav/flac/ogg, ≤30MB)"),
+    o: str | None = typer.Option(None, "-o", "--output"),
+    idempotency_key: str | None = typer.Option(None, "--idempotency-key"),
+    json_out: bool = typer.Option(False, "--json", help="Machine-readable single-JSON output."),
+) -> None:
+    cfg = _cfg(None, None)
+    p = _audio_path(file, json_out)
+    _check_output(o, json_out)
+    with _api(cfg, json_out) as c, _open_audio(p, json_out) as fh:
+        r = c.post(
+            cfg["base_url"] + "/stt",
+            headers=auth_headers(cfg["api_key"], idempotency_key),
+            files={"file": (p.name, fh)},
+        )
+        raise_for_api(r.status_code, r.text, "/stt")
+    output.present(
+        r.text,
+        {
+            "units": r.headers.get("x-units", ""),
+            "cache": r.headers.get("x-cache-status", ""),
+            "request_id": r.headers.get("x-request-id", ""),
+        },
+        json_out, o,
+    )
+
+@app.command()
+def tts(
+    text: str = typer.Argument("", help="Text to synthesize"),
+    o: str = typer.Option(..., "-o", "--output", help="Output wav path (required)"),
+    text_file: str | None = typer.Option(None, "--text-file"),
+    idempotency_key: str | None = typer.Option(None, "--idempotency-key"),
+    json_out: bool = typer.Option(False, "--json", help="Machine-readable single-JSON output."),
+) -> None:
+    cfg = _cfg(None, None)
+    if text_file:
+        try:
+            text = _Path(text_file).read_text(encoding="utf-8").strip()
+        except (FileNotFoundError, IsADirectoryError, OSError, ValueError) as e:
+            output.print_err(f"cannot read --text-file: {e}", "check the path", json_out)
+            raise typer.Exit(1)
+    if not text.strip():
+        output.print_err("empty text", "provide TEXT or --text-file", json_out)
+        raise typer.Exit(1)
+    _check_output(o, json_out)
+    if not json_out:
+        typer.echo(f"words={len(text.split())}")
+    with _api(cfg, json_out) as c:
+        r = c.post(
+            cfg["base_url"] + "/tts",
+            headers={**auth_headers(cfg["api_key"], idempotency_key), "Content-Type": "application/json"},
+            json={"text": text},
+        )
+        raise_for_api(r.status_code, r.text, "/tts")
+    output.save_bytes(o, r.content, json_out)
+    output.print_ok({"units": r.headers.get("x-units", ""), "cache": r.headers.get("x-cache-status", ""), "request_id": r.headers.get("x-request-id", "")}, json_out)
+
+@app.command()
+def mt(
+    text: str = typer.Argument(..., help="Text to translate"),
+    src: str = typer.Option("rw", "--src"),
+    tgt: str = typer.Option("en", "--tgt"),
+    o: str | None = typer.Option(None, "-o", "--output"),
+    idempotency_key: str | None = typer.Option(None, "--idempotency-key"),
+    json_out: bool = typer.Option(False, "--json", help="Machine-readable single-JSON output."),
+) -> None:
+    cfg = _cfg(None, None)
+    if src not in ("rw", "en") or tgt not in ("rw", "en"):
+        output.print_err(f"unsupported lang src={src} tgt={tgt}", "use --src rw|en --tgt rw|en", json_out)
+        raise typer.Exit(1)
+    if src == tgt:
+        output.print_err("src==tgt", "source and target must differ", json_out)
+        raise typer.Exit(1)
+    if not text.strip():
+        output.print_err("empty text", "provide TEXT", json_out)
+        raise typer.Exit(1)
+    _check_output(o, json_out)
+    with _api(cfg, json_out) as c:
+        r = c.post(
+            cfg["base_url"] + "/mt",
+            headers={**auth_headers(cfg["api_key"], idempotency_key), "Content-Type": "application/json"},
+            json={"text": text, "source_lang": src, "target_lang": tgt},
+        )
+        raise_for_api(r.status_code, r.text, "/mt")
+    output.present(
+        r.text,
+        {
+            "units": r.headers.get("x-units", ""),
+            "cache": r.headers.get("x-cache-status", ""),
+            "request_id": r.headers.get("x-request-id", ""),
+        },
+        json_out, o,
+    )
+
+@app.command()
+def diarize(
+    file: str = typer.Argument(..., help="Audio file (≤30MB)"),
+    o: str | None = typer.Option(None, "-o", "--output"),
+    fmt: str = typer.Option("json", "--format", help="json|txt|srt"),
+    idempotency_key: str | None = typer.Option(None, "--idempotency-key"),
+    json_out: bool = typer.Option(False, "--json", help="Machine-readable single-JSON output."),
+) -> None:
+    cfg = _cfg(None, None)
+    if fmt not in ("json", "txt", "srt"):
+        output.print_err(f"bad format {fmt}", "use --format json|txt|srt", json_out)
+        raise typer.Exit(1)
+    p = _audio_path(file, json_out)
+    _check_output(o, json_out)
+    with _api(cfg, json_out) as c, _open_audio(p, json_out) as fh:
+        r = c.post(
+            cfg["base_url"] + "/diarize",
+            headers=auth_headers(cfg["api_key"], idempotency_key),
+            files={"file": (p.name, fh)},
+        )
+        raise_for_api(r.status_code, r.text, "/diarize")
+    try:
+        data = r.json()
+        segs = data.get("segments", []) if isinstance(data, dict) else None
+        if not isinstance(segs, list) or not all(isinstance(s, dict) for s in segs):
+            raise ValueError("segments must be a list of objects")
+        rendered = _render_segments(segs, fmt)
+    except (TypeError, ValueError):
+        output.print_err("invalid diarize response", "try `duhub health --detailed`", json_out)
+        raise typer.Exit(1)
+    output.present(
+        rendered,
+        {"units": r.headers.get("x-units", ""), "cache": "", "request_id": r.headers.get("x-request-id", "")},
+        json_out, o,
+    )
+
+
+if __name__ == "__main__":
+    app()

du_cli/output.py

@@ -0,0 +1,104 @@
+"""Human (Rich) vs machine (--json) output. No binary to stdout."""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.markup import escape
+
+_console = Console()
+_console_err = Console(stderr=True)
+
+def summary_line(units: str | None, cache: str | None, request_id: str | None) -> str:
+    parts = []
+    if units is not None:
+        parts.append(f"units={units}")
+    if cache is not None:
+        parts.append(f"cache={cache}")
+    if request_id is not None:
+        parts.append(f"request-id={request_id}")
+    return " ".join(parts) if parts else "ok"
+
+def render_segments(segments: list[dict], fmt: str) -> str:
+    if fmt == "json":
+        return json.dumps(segments, ensure_ascii=False, indent=2)
+    if fmt == "txt":
+        return "\n".join(f"[Speaker {s.get('speaker')}] {s.get('text', '')}" for s in segments)
+    if fmt == "srt":
+        def ts(x: float) -> str:
+            total_ms = round(float(x) * 1000)
+            h, rem = divmod(total_ms, 3_600_000)
+            m, rem = divmod(rem, 60_000)
+            sec, ms = divmod(rem, 1000)
+            return f"{h:02d}:{m:02d}:{sec:02d},{ms:03d}"
+        lines = []
+        for i, s in enumerate(segments, 1):
+            lines.append(str(i))
+            lines.append(f"{ts(float(s.get('start', 0)))} --> {ts(float(s.get('end', 0)))}")
+            lines.append(f"[Speaker {s.get('speaker')}] {s.get('text', '')}")
+            lines.append("")
+        return "\n".join(lines)
+    raise ValueError(f"unknown format: {fmt}")
+
+def print_ok(summary: dict[str, str], as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(summary, ensure_ascii=False))
+    else:
+        _console.print(f"[green]ok[/green] {summary_line(summary.get('units'), summary.get('cache'), summary.get('request_id'))}")
+
+def print_err(error: str, hint: str, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps({"error": error, "hint": hint}, ensure_ascii=False), file=sys.stderr)
+    else:
+        _console_err.print(f"[red]error:[/red] {escape(error)}\nhint: {escape(hint)}")
+
+def check_output_path(path: str, as_json: bool) -> None:
+    """Fail early (before a billed API call) when the output path is unusable."""
+    p = Path(path)
+    try:
+        if p.exists() and p.is_dir():
+            raise IsADirectoryError(f"is a directory: {path}")
+        parent = p.parent
+        if not parent.exists():
+            raise FileNotFoundError(f"parent directory does not exist: {parent}")
+        if not parent.is_dir():
+            raise NotADirectoryError(f"not a directory: {parent}")
+    except OSError as e:
+        print_err(f"cannot write {path}: {e}", "check the path and permissions", as_json)
+        raise typer.Exit(1)
+
+def _write(path: str, data: str | bytes, as_json: bool) -> None:
+    check_output_path(path, as_json)
+    try:
+        p = Path(path)
+        if isinstance(data, bytes):
+            p.write_bytes(data)
+        else:
+            p.write_text(data, encoding="utf-8")
+    except OSError as e:
+        print_err(f"cannot write {path}: {e}", "check the path and permissions", as_json)
+        raise typer.Exit(1)
+
+def save_bytes(path: str, data: bytes, as_json: bool) -> None:
+    """Write a binary payload (e.g. TTS wav) with a clean CLI error on failure."""
+    _write(path, data, as_json)
+
+def present(text: str, summary: dict[str, str], as_json: bool, o: str | None) -> None:
+    """One payload outlet: -o writes the raw file; stdout is a single JSON
+    object under --json, else raw text plus the human ok-line."""
+    if o:
+        _write(o, text, as_json)
+        print_ok(summary, as_json)
+        return
+    if as_json:
+        try:
+            data = json.loads(text)
+        except ValueError:
+            data = text
+        print(json.dumps({"data": data, **summary}, ensure_ascii=False))
+    else:
+        print(text)
+        print_ok(summary, False)

duhub_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: duhub-cli
+Version: 0.1.0
+Summary: DUhub CLI — STT, TTS, MT and diarization over your API key.
+Author: Digital Umuganda
+License-Expression: MIT
+Project-URL: Homepage, https://beta.duhub.ai
+Project-URL: Repository, https://github.com/Digital-Umuganda/duhub-cli
+Project-URL: Issues, https://github.com/Digital-Umuganda/duhub-cli/issues
+Keywords: kinyarwanda,stt,tts,translation,diarization,speech
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.9
+Requires-Dist: rich>=13
+Requires-Dist: httpx>=0.27
+Dynamic: license-file
+
+# duhub-cli
+
+Command-line client for [DUhub](https://beta.duhub.ai):
+transcribe audio, synthesize speech, translate text, and diarize meetings —
+all billed to your API key.
+
+```bash
+duhub stt rec.wav -o transcript.json
+duhub tts "Muraho neza nshuti yanjye." -o out.wav
+duhub mt "Muraho" --src rw --tgt en
+duhub diarize meeting.wav --format srt -o speakers.srt
+```
+
+## Installation
+
+Requires Python 3.11+.
+
+```bash
+pipx install duhub-cli
+duhub --version
+```
+
+Alternatives:
+
+```bash
+pipx install git+https://github.com/Digital-Umuganda/duhub-cli.git
+pip install git+https://github.com/Digital-Umuganda/duhub-cli.git   # plain pip
+python -m du_cli.main --help                                     # without installing
+```
+
+> The installed command is `duhub` only, so it does not shadow the Unix
+> `du` (disk usage). You can also invoke `python -m du_cli.main` without
+> installing.
+
+## Quickstart
+
+1. Create an account on the
+   [Dashboard](https://beta.duhub.ai) and copy an
+   API key from **API Keys** (shown once — treat it like a password).
+2. Save it:
+   ```bash
+   duhub configure --api-key du_live_xxxxxxxxxxxxxxxx
+   ```
+3. Check connectivity:
+   ```bash
+   duhub health
+   duhub health --detailed
+   ```
+4. Transcribe something:
+   ```bash
+   duhub stt rec.wav
+   ```
+
+## Configuration
+
+`duhub configure` stores settings in `~/.config/du/config.toml`:
+
+| Source | Priority | Example |
+|--------|----------|---------|
+| Environment | Highest (always wins) | `DU_API_KEY`, `DU_BASE_URL` |
+| Config file | Middle | `duhub configure --api-key … --base-url …` |
+| Built-in default | Lowest | base `https://du-api.dev.umuganda.digital` |
+
+```bash
+duhub configure                                # show current state
+duhub configure --api-key du_live_xxx          # set key
+duhub configure --base-url http://localhost:8080  # point at local gateway
+duhub configure --reset                        # delete the file
+export DU_API_KEY=du_live_xxx DU_BASE_URL=https://du-api.dev.umuganda.digital
+```
+
+> Prefer `DU_API_KEY` env var over `--api-key` — flags land in shell history.
+
+## Commands
+
+Every command exits `0` on success, `1` on failure (`2` on CLI usage
+errors) and prints a summary line (`units`, `cache`, `request-id`). The
+API commands (`health`, `stt`, `tts`, `mt`, `diarize`) accept `--json`
+for a single machine-readable object on stdout
+(`{"data", "units", "cache", "request_id"}`). `-o` writes the raw
+payload to a file instead of stdout.
+
+Every billed command (`stt`, `tts`, `mt`, `diarize`) accepts
+`--idempotency-key`, so a retry after a timeout or connection drop is
+deduplicated by the gateway instead of being billed twice.
+
+### `duhub health`
+
+Liveness (`/health`) or full readiness (`--detailed`, checks STT/TTS/MT
+backends — the one to try first when calls fail).
+
+### `duhub stt` — speech to text
+
+Upload audio (WAV/FLAC/OGG, ≤ 30 MB), get `{"text": "…"}`.
+**Billed per audio second.**
+
+```bash
+duhub stt rec.wav -o transcript.json
+duhub stt rec.wav --idempotency-key run-42 -o transcript.json
+```
+
+### `duhub tts` — text to speech
+
+Synthesize Kinyarwanda speech to a 24 kHz mono WAV (`-o` is required —
+audio never goes to stdout). **Billed per word.** `--text-file`
+overrides `TEXT` when both are given.
+
+```bash
+duhub tts "Muraho neza nshuti yanjye." -o out.wav
+duhub tts "Muraho neza nshuti yanjye." -o out.wav --idempotency-key run-42
+```
+
+### `duhub mt` — translation
+
+Translate between Kinyarwanda (`rw`) and English (`en`).
+**Billed per input word.**
+
+```bash
+duhub mt "Muraho" --src rw --tgt en
+```
+
+### `duhub diarize` — who spoke when
+
+Upload audio, get speaker-labelled segments. `--format` renders the same
+result as `json` (default), `txt`, or `srt`. **Billed per audio second.**
+
+```bash
+duhub diarize meeting.wav --format srt -o speakers.srt
+```
+
+> A `404` here usually means the configured gateway predates the
+> `/diarize` route. Check `duhub health --detailed` and your `--base-url`.
+
+## Scripting
+
+`--json` prints exactly one JSON object — pipe-safe:
+
+```bash
+TEXT=$(duhub stt rec.wav --json | jq -r .data.text)
+
+for f in clips/*.wav; do
+  duhub stt "$f" -o "${f%.wav}.json" || echo "FAILED: $f" >&2
+done
+```
+
+## Errors
+
+API, input-file, and output-file failures are reported as `error` +
+`hint` — no tracebacks:
+
+| You see | Cause | Fix |
+|---------|-------|-----|
+| `invalid key` (401) | Missing/unknown/revoked key | Copy a fresh key from dashboard API Keys |
+| `insufficient balance` (402) | Wallet empty | Top-up via dashboard Wallet |
+| `organization pending review` (403) | Org not approved yet | Contact your org admin |
+| `file exceeds 30 MB` | Upload guard | Compress or split the audio |
+| `server busy (saturated)` (503) | GPU at concurrency cap | Wait `Retry-After` seconds, retry |
+| `backend unreachable` (502) | Model container down | `duhub health --detailed` to see which |
+| `cannot reach server` | Wrong `--base-url`, offline, timeout | Check URL and connectivity |
+
+## Development
+
+```bash
+uv sync        # or: python -m venv .venv && .venv/bin/pip install -e .
+uv run pytest
+uv run duhub --help
+```

duhub_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+du_cli/__init__.py,sha256=ZdroH7KM49mKbJMV4Dnl_FVAlDjRHaRWgn3sjWnkE2s,57
+du_cli/client.py,sha256=JvPZfXmNKg5KA4U-vJQEahNpZCErWlHWwJE2KyblEhY,2308
+du_cli/config.py,sha256=yF29tGA-1uy_kk9xO1PfL75f8CDwVTGZQQYThdlmzuw,2423
+du_cli/main.py,sha256=zwA_aalTJtynMepxpe7xH5IBFzuYdXNr8Bpary_bR_0,10227
+du_cli/output.py,sha256=H5luZKqtmQ4OC6xoBDj-dsC0zKFYFiBq6JLZlLyujRQ,3933
+duhub_cli-0.1.0.dist-info/licenses/LICENSE,sha256=wxI7NZ1OvtXusPXaEmhy8efO9XmMa2kKaP93sNm4ZZ8,1073
+duhub_cli-0.1.0.dist-info/METADATA,sha256=_MSkIXA-WzUcPxVGvnv1VPC8yMIgwbfEJzezdTosAp8,6081
+duhub_cli-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+duhub_cli-0.1.0.dist-info/entry_points.txt,sha256=p4hxWWISD3zKwahc6VfelZZLtmoIctfb1fkDko1xzXQ,42
+duhub_cli-0.1.0.dist-info/top_level.txt,sha256=RLpZ8i7eI0S9TUmL0jPcQLB9lG3er8Lr-IcNYm8Zlxc,7
+duhub_cli-0.1.0.dist-info/RECORD,,

duhub_cli-0.1.0.dist-info/WHEEL

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

duhub_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+duhub = du_cli.main:app

duhub_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Digital Umuganda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

duhub_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+du_cli