duhub-cli 0.1.0__tar.gz

duhub_cli-0.1.0/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/PKG-INFO

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

@@ -0,0 +1,167 @@
+# 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/du_cli/__init__.py

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

duhub_cli-0.1.0/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))

duhub_cli-0.1.0/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