venice-cli 0.14.0__py3-none-any.whl

venice/client.py

@@ -0,0 +1,258 @@
+"""Thin Venice.ai HTTP client built on urllib. No third-party deps.
+
+Returns dicts for JSON responses, bytes for binary (audio/image).
+Maps non-2xx to VeniceAPIError with status, URL, and a body excerpt.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable, Optional, Tuple, Union
+
+from . import config
+
+
+class VeniceAPIError(Exception):
+    """HTTP-level error from the Venice API.
+
+    Attributes:
+        status: HTTP status code (0 if connection failed pre-response).
+        url:    final request URL.
+        body:   excerpt of the response body (first ~2 KB), for debugging.
+        code:   Venice API error code (e.g. INSUFFICIENT_BALANCE), if parseable.
+    """
+
+    def __init__(self, status: int, url: str, body: str, code: Optional[str] = None):
+        self.status = status
+        self.url = url
+        self.body = body
+        self.code = code
+        msg = f"HTTP {status} from {url}"
+        if code:
+            msg += f" [{code}]"
+        if body:
+            msg += f"\n  body: {body[:500]}"
+        super().__init__(msg)
+
+
+ResponseType = Union[dict, bytes]
+
+
+class VeniceClient:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: Optional[str] = None,
+        timeout: float = 60.0,
+        user_agent: str = "venice-cli/0.1",
+    ):
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.api_key = api_key
+        self.base_url = (base_url or config.DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.user_agent = user_agent
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Optional[dict] = None,
+        params: Optional[dict] = None,
+    ) -> Tuple[int, str, bytes]:
+        url = self.base_url + path
+        if params:
+            url += "?" + urllib.parse.urlencode(params, doseq=True)
+
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json, audio/*, image/*, video/*",
+            "User-Agent": self.user_agent,
+        }
+        data: Optional[bytes] = None
+        if json_body is not None:
+            data = json.dumps(json_body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                body = resp.read()
+                ctype = resp.headers.get("Content-Type", "")
+                status = getattr(resp, "status", 200)
+                return status, ctype, body
+        except urllib.error.HTTPError as e:
+            err_body = b""
+            try:
+                err_body = e.read()
+            except Exception:
+                pass
+            err_ctype = ""
+            try:
+                err_ctype = e.headers.get("Content-Type", "")
+            except Exception:
+                pass
+            self._raise_api_error(e.code, url, err_body, err_ctype)
+        except urllib.error.URLError as e:
+            raise VeniceAPIError(0, url, f"connection error: {e.reason}") from None
+
+    def post_json(self, path: str, body: dict) -> dict:
+        status, ctype, raw = self.request("POST", path, json_body=body)
+        return self._decode_json(status, path, ctype, raw)
+
+    def get_json(self, path: str, params: Optional[dict] = None) -> dict:
+        status, ctype, raw = self.request("GET", path, params=params)
+        return self._decode_json(status, path, ctype, raw)
+
+    def post_for_bytes_or_json(
+        self, path: str, body: dict
+    ) -> Tuple[str, ResponseType]:
+        """For endpoints that may return JSON (in-progress) OR binary (done).
+
+        Used by /audio/retrieve. Returns (content_type, payload):
+          - ("audio/mpeg", b"...") on completion
+          - ("application/json", {...}) while still processing
+        """
+        status, ctype, raw = self.request("POST", path, json_body=body)
+        ct_low = (ctype or "").lower()
+        if ct_low.startswith("application/json"):
+            return ctype, (json.loads(raw.decode("utf-8")) if raw else {})
+        if (
+            ct_low.startswith("audio/")
+            or ct_low.startswith("image/")
+            or ct_low.startswith("video/")
+        ):
+            return ctype, raw
+        return ctype, raw
+
+    def poll_retrieve(
+        self,
+        path: str,
+        body: dict,
+        *,
+        interval: float = config.SFX_POLL_INTERVAL_SEC,
+        max_wait: float = config.SFX_POLL_MAX_WAIT_SEC,
+        on_tick: Optional[Callable[[dict], None]] = None,
+        terminal_statuses: Tuple[str, ...] = (),
+    ) -> Tuple[str, ResponseType]:
+        """Poll an async endpoint that switches content-type on completion.
+
+        On success returns (content_type, payload):
+          - (ctype, bytes) when the endpoint streams the finished media, or
+          - (ctype, dict) when the JSON `status` is in `terminal_statuses`
+            (e.g. video's "COMPLETED" -- the media is fetched separately from a
+            download_url). Audio callers leave `terminal_statuses` empty and
+            always get bytes.
+
+        Raises VeniceAPIError on terminal HTTP errors or an unexpected status.
+        Raises TimeoutError if max_wait elapses while still PROCESSING.
+        """
+        deadline = time.monotonic() + max_wait
+        while True:
+            ctype, payload = self.post_for_bytes_or_json(path, body)
+            if isinstance(payload, (bytes, bytearray)):
+                return ctype, bytes(payload)
+            if not isinstance(payload, dict):
+                raise VeniceAPIError(
+                    0, path, f"unexpected payload type from {path}: {type(payload).__name__}"
+                )
+            status = payload.get("status")
+            if status and status in terminal_statuses:
+                return ctype, payload
+            if status and status != "PROCESSING":
+                raise VeniceAPIError(
+                    0, path, f"unexpected status: {payload!r}"
+                )
+            if on_tick:
+                try:
+                    on_tick(payload)
+                except Exception:
+                    pass
+            if time.monotonic() >= deadline:
+                raise TimeoutError(
+                    f"not ready after {max_wait}s "
+                    f"(last status: {status!r})"
+                )
+            time.sleep(interval)
+
+    def get_url_bytes(self, url: str) -> Tuple[str, bytes]:
+        """Fetch an arbitrary URL's bytes with a plain GET (no auth header).
+
+        For presigned download URLs (e.g. a video's download_url), which carry
+        their own auth in the query string and must not receive our Bearer token.
+        Returns (content_type, bytes); maps HTTP/URL errors to VeniceAPIError.
+        """
+        req = urllib.request.Request(
+            url, headers={"User-Agent": self.user_agent}, method="GET"
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return resp.headers.get("Content-Type", ""), resp.read()
+        except urllib.error.HTTPError as e:
+            err_body = b""
+            try:
+                err_body = e.read()
+            except Exception:
+                pass
+            self._raise_api_error(e.code, url, err_body, "")
+        except urllib.error.URLError as e:
+            raise VeniceAPIError(0, url, f"connection error: {e.reason}") from None
+
+    @staticmethod
+    def _decode_json(status: int, path: str, ctype: str, raw: bytes) -> dict:
+        if not raw:
+            return {}
+        try:
+            return json.loads(raw.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as e:
+            raise VeniceAPIError(
+                status, path, f"non-JSON response ({ctype}): {e}"
+            ) from None
+
+    def get_balance(self) -> Optional[dict]:
+        """Fetch current balance + tier via /api_keys/rate_limits.
+
+        Returns the parsed `data` block (with balances, apiTier, nextEpochBegins,
+        rateLimits) or None if the call fails. Best-effort; callers should
+        treat None as "balance unavailable, continue".
+        """
+        try:
+            doc = self.get_json("/api_keys/rate_limits")
+        except VeniceAPIError:
+            return None
+        data = doc.get("data") if isinstance(doc, dict) else None
+        return data if isinstance(data, dict) else None
+
+    @staticmethod
+    def _raise_api_error(status: int, url: str, body: bytes, ctype: str):
+        excerpt = ""
+        code: Optional[str] = None
+        try:
+            text = body.decode("utf-8", errors="replace")
+            excerpt = text[:2048]
+            if (ctype or "").lower().startswith("application/json"):
+                doc: Any = json.loads(text)
+                if isinstance(doc, dict):
+                    code = doc.get("code")
+                    if not code and isinstance(doc.get("error"), dict):
+                        code = doc["error"].get("code")
+        except Exception:
+            pass
+        raise VeniceAPIError(status, url, excerpt, code=code)
+
+
+def build_client_from_auth():
+    """Construct a VeniceClient using env-var or file credentials.
+
+    Raises auth.AuthError if no key is available. Honors $VENICE_BASE_URL.
+    """
+    from . import auth
+
+    key = auth.load_key()
+    base = os.environ.get(config.ENV_BASE_URL) or config.DEFAULT_BASE_URL
+    return VeniceClient(api_key=key, base_url=base)

venice/commands/__init__.py

@@ -0,0 +1,22 @@
+"""Single import point. Adding a subcommand = one import + one tuple entry."""
+from . import balance, bg_remove, chat, contact_sheet, embed, image, login, master, models, music, sfx, tts, upscale, video
+
+
+def register_all(subparsers) -> None:
+    login.register(subparsers)
+    balance.register(subparsers)
+    models.register(subparsers)
+    sfx.register(subparsers)
+    sfx.register_status(subparsers)
+    music.register(subparsers)
+    music.register_status(subparsers)
+    video.register(subparsers)
+    video.register_status(subparsers)
+    chat.register(subparsers)
+    tts.register(subparsers)
+    image.register(subparsers)
+    upscale.register(subparsers)
+    bg_remove.register(subparsers)
+    embed.register(subparsers)
+    master.register(subparsers)
+    contact_sheet.register(subparsers)

venice/commands/_audio.py

@@ -0,0 +1,96 @@
+"""Audio-specific glue over the shared async-queue engine (`_queue`).
+
+`sfx` and `music` share this: the endpoint-agnostic quote/queue/poll plumbing
+lives in `_queue`; here we keep the audio content-type map and the
+audio-specialized `retrieve_and_save` (optional post-processing + playback).
+"""
+from __future__ import annotations
+
+import sys
+import time
+from pathlib import Path
+from typing import Callable, Optional, Tuple
+
+from .. import audio_player
+from ..client import VeniceAPIError
+from . import _queue
+
+EXT_BY_CTYPE = {
+    "audio/mpeg": ".mp3",
+    "audio/mp3": ".mp3",
+    "audio/wav": ".wav",
+    "audio/wave": ".wav",
+    "audio/x-wav": ".wav",
+    "audio/flac": ".flac",
+}
+
+
+def ext_for(ctype: str) -> Tuple[str, bool]:
+    return _queue.ext_for(ctype, EXT_BY_CTYPE)
+
+
+def retrieve_and_save(
+    client,
+    model: str,
+    queue_id: str,
+    out_arg: Optional[Path],
+    poll_interval: float,
+    max_wait: float,
+    no_cleanup: bool,
+    want_play: Optional[bool],
+    *,
+    name_prefix: str,
+    retry_hint: str,
+    post_process: Optional[Callable[[Path], int]] = None,
+) -> int:
+    body = {"model": model, "queue_id": queue_id}
+    start = time.monotonic()
+    try:
+        ctype, audio = client.poll_retrieve(
+            "/audio/retrieve",
+            body,
+            interval=poll_interval,
+            max_wait=max_wait,
+            on_tick=_queue.progress_tick(start),
+        )
+    except VeniceAPIError as e:
+        sys.stderr.write("\n")
+        print(f"retrieve failed: {e}", file=sys.stderr)
+        return _queue.status_to_exit(e)
+    except TimeoutError as e:
+        sys.stderr.write("\n")
+        print(f"{e}; check later with: {retry_hint}", file=sys.stderr)
+        return 7
+    sys.stderr.write("\n")
+
+    ext, unknown = ext_for(ctype)
+    if unknown:
+        print(f"warning: unexpected content-type {ctype!r}; saving as .bin", file=sys.stderr)
+    out_path = _queue.resolve_output_path(out_arg, queue_id, ext, prefix=name_prefix)
+
+    try:
+        out_path.write_bytes(audio)
+    except OSError as e:
+        print(f"could not write {out_path}: {e}", file=sys.stderr)
+        return 9
+
+    abs_path = out_path.resolve()
+    print(str(abs_path))
+    print(f"wrote {len(audio)} bytes to {abs_path}", file=sys.stderr)
+
+    if not no_cleanup:
+        try:
+            client.post_json("/audio/complete", {"model": model, "queue_id": queue_id})
+        except VeniceAPIError as e:
+            print(f"warning: cleanup call failed: {e}", file=sys.stderr)
+
+    post_rc = 0
+    if post_process is not None:
+        post_rc = post_process(out_path)
+
+    should_play = want_play
+    if should_play is None:
+        should_play = sys.stdout.isatty() and audio_player.has_player()
+    if should_play:
+        audio_player.play(out_path)
+    return post_rc

venice/commands/_models.py

@@ -0,0 +1,83 @@
+"""Shared model-catalog resolution for commands that pick a model by id.
+
+Extracted from `chat` so it, `embed`, and `video` share one copy of the free
+`/models?type=...` GET plus the default-trait/validation logic rather than each
+carrying its own. These helpers take primitive args (a model type, the requested
+id, a label and noun for messages) so they stay independent of any one command's
+argument shape.
+
+The catalog GET is free, so commands call it before the paid request to validate
+`--model` and resolve a default without spending.
+"""
+from __future__ import annotations
+
+import sys
+from typing import List, Optional, Tuple
+
+from ..client import VeniceAPIError
+
+
+def catalog(client, model_type: str) -> Optional[List[dict]]:
+    """Fetch the model catalog for `model_type` ("text", "embedding", "video").
+
+    None if the (free) GET is unavailable, which leaves the caller unable to
+    validate or pick a default.
+    """
+    try:
+        doc = client.get_json("/models", params={"type": model_type})
+    except VeniceAPIError:
+        return None
+    data = doc.get("data") if isinstance(doc, dict) else None
+    return list(data) if isinstance(data, list) else None
+
+
+def default_model(models: List[dict]) -> Optional[str]:
+    """The id of the first model advertising the 'default' trait, if any."""
+    for m in models:
+        spec = m.get("model_spec") if isinstance(m, dict) else None
+        traits = spec.get("traits") if isinstance(spec, dict) else None
+        if isinstance(traits, list) and "default" in traits:
+            return m.get("id")
+    return None
+
+
+def resolve_model(
+    requested: Optional[str],
+    models: Optional[List[dict]],
+    *,
+    label: str,
+    noun: str,
+) -> Tuple[Optional[str], Optional[int]]:
+    """Validate `requested` against the catalog, or pick the default.
+
+    Returns (model_id, exit_code). exit_code is None on success. `label` prefixes
+    error messages (e.g. "chat") and `noun` names the model kind in them (e.g.
+    "text model").
+    """
+    if models is None:
+        # Catalog unavailable: can't validate or pick a default.
+        if requested:
+            return requested, None
+        print(
+            f"{label}: could not fetch the model catalog; pass --model explicitly",
+            file=sys.stderr,
+        )
+        return None, 2
+
+    ids = [m.get("id") for m in models if isinstance(m, dict) and m.get("id")]
+    if requested:
+        if requested in ids:
+            return requested, None
+        print(f"{label}: unknown {noun} {requested!r}", file=sys.stderr)
+        print("available: " + ", ".join(ids), file=sys.stderr)
+        return None, 6
+
+    default = default_model(models)
+    if default:
+        return default, None
+    print(
+        f"{label}: no default {noun} advertised; pass --model. "
+        "available: " + ", ".join(ids),
+        file=sys.stderr,
+    )
+    return None, 6

venice/commands/_openai.py

@@ -0,0 +1,62 @@
+"""Shared `openai` SDK plumbing for Venice's OpenAI-compatible endpoints.
+
+Extracted from `chat` so it and `embed` share one copy of the lazy-import probe,
+the SDK client construction, and the exception -> exit-code mapping rather than
+each carrying its own. These helpers take primitive args (a label for messages,
+the imported module, an exception) so they stay independent of any one command's
+argument shape.
+
+The SDK is imported lazily -- the rest of the CLI is stdlib-only, so a missing
+`openai` must degrade to a hint and exit 2 rather than break `venice --help`.
+Callers probe the import *first*, before building a client or fetching a
+catalog, so the missing-SDK path never touches the network.
+"""
+from __future__ import annotations
+
+import sys
+
+
+def import_openai(label: str):
+    """Import the openai SDK lazily. None (after printing a hint) if absent.
+
+    `label` names the command in the hint (e.g. "chat").
+    """
+    try:
+        import openai
+    except ImportError:
+        print(
+            f"venice {label} needs the openai package: "
+            'pip install "venice-cli[openai]" (or: pip install openai)',
+            file=sys.stderr,
+        )
+        return None
+    return openai
+
+
+def build_openai(module, client):
+    """Build an SDK client pointed at Venice, borrowing the lean client's auth."""
+    return module.OpenAI(api_key=client.api_key, base_url=client.base_url)
+
+
+def status_to_exit(module, e, label: str) -> int:
+    """Map an openai SDK exception to a venice exit code.
+
+    `module` is the imported openai module (for its exception types) and `label`
+    prefixes the message (e.g. "chat").
+    """
+    if isinstance(e, module.APIConnectionError):
+        print(f"{label}: connection error: {e}", file=sys.stderr)
+        return 8
+    status = getattr(e, "status_code", None)
+    print(f"{label}: API error: {e}", file=sys.stderr)
+    if status == 401:
+        return 2
+    if status == 404:
+        return 6
+    if status == 429:
+        return 4
+    if isinstance(status, int) and 500 <= status < 600:
+        return 5
+    if isinstance(status, int) and 400 <= status < 500:
+        return 2
+    return 5

venice/commands/_queue.py

@@ -0,0 +1,87 @@
+"""Shared async-queue engine for Venice's quote -> queue -> poll -> retrieve
+-> complete endpoints.
+
+Endpoint-agnostic primitives factored out of `_audio` so audio (`sfx`/`music`)
+and video can share one copy of the plumbing. Callers pass primitive args
+(model, queue_id, paths, an extension map) so these helpers stay independent of
+any one command's argument shape.
+"""
+from __future__ import annotations
+
+import sys
+import time
+from pathlib import Path
+from typing import Optional, Tuple
+
+from .. import auth
+from ..client import VeniceAPIError, build_client_from_auth
+
+
+def build_client():
+    try:
+        return build_client_from_auth(), 0
+    except auth.AuthError as e:
+        print(str(e), file=sys.stderr)
+        return None, 2
+
+
+def ext_for(ctype: str, ext_map: dict, default: str = ".bin") -> Tuple[str, bool]:
+    """Map a response content-type to a file extension.
+
+    Returns (ext, unknown): `unknown` is True when the type wasn't in the map,
+    in which case `default` is returned so the caller can warn.
+    """
+    base = (ctype or "").split(";", 1)[0].strip().lower()
+    if base in ext_map:
+        return ext_map[base], False
+    return default, True
+
+
+def resolve_output_path(
+    arg_output: Optional[Path], queue_id: str, ext: str, *, prefix: str
+) -> Path:
+    short = (queue_id or "unknown")[:8]
+    default_name = f"{prefix}-{short}{ext}"
+    if arg_output is None:
+        return Path.cwd() / default_name
+    if arg_output.is_dir():
+        return arg_output / default_name
+    return arg_output
+
+
+def status_to_exit(err: VeniceAPIError) -> int:
+    s = err.status
+    if s == 422:
+        return 3
+    if s == 429:
+        return 4
+    if 500 <= s < 600:
+        return 5
+    if s == 404:
+        return 6
+    if s == 0:
+        return 8
+    return 2
+
+
+def progress_tick(start: float):
+    def _on(payload: dict) -> None:
+        avg_ms = payload.get("average_execution_time") or 0
+        elapsed_ms = payload.get("execution_duration") or 0
+        try:
+            avg_s = float(avg_ms) / 1000.0
+        except (TypeError, ValueError):
+            avg_s = 0.0
+        try:
+            el_s = float(elapsed_ms) / 1000.0
+        except (TypeError, ValueError):
+            el_s = 0.0
+        wall = time.monotonic() - start
+        if avg_s > 0:
+            sys.stderr.write(
+                f"\r[wall {wall:5.1f}s | server {el_s:5.1f}s / ~{avg_s:5.1f}s] processing..."
+            )
+        else:
+            sys.stderr.write(f"\r[wall {wall:5.1f}s] processing...")
+        sys.stderr.flush()
+    return _on