otari-cli 0.1.0__py3-none-any.whl

otari_cli/__init__.py

@@ -0,0 +1,18 @@
+"""otari-cli - command-line interface for the otari LLM gateway and platform.
+
+The CLI is a thin shell over the :mod:`otari` Python client SDK. It resolves
+connection settings from flags or the same environment variables the SDK reads,
+then maps subcommands onto the SDK's :class:`otari.OtariClient` and its
+control-plane resources.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("otari-cli")
+except PackageNotFoundError:
+    __version__ = "0.0.0-dev"
+
+__all__ = ["__version__"]

otari_cli/__main__.py

@@ -0,0 +1,8 @@
+"""Entry point for ``python -m otari_cli``."""
+
+from __future__ import annotations
+
+from otari_cli.cli import main
+
+if __name__ == "__main__":
+    main()

otari_cli/_client.py

@@ -0,0 +1,43 @@
+"""Construction of the :class:`otari.OtariClient` from resolved CLI config.
+
+Command modules call :func:`build_client` indirectly (via the module, e.g.
+``_client.build_client(...)``) so tests can substitute a fake client by
+monkeypatching this single seam.
+"""
+
+from __future__ import annotations
+
+import contextlib
+from typing import TYPE_CHECKING
+
+from otari import OtariClient
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from otari_cli.config import OtariConfig
+
+
+def build_client(config: OtariConfig) -> OtariClient:
+    """Build an :class:`otari.OtariClient` from resolved connection settings."""
+    return OtariClient(
+        api_base=config.api_base,
+        api_key=config.api_key,
+        platform_token=config.platform_token,
+        admin_key=config.admin_key,
+    )
+
+
+@contextlib.contextmanager
+def session(config: OtariConfig) -> Iterator[OtariClient]:
+    """Yield a client built from ``config``, closing it on exit.
+
+    Construct the client lazily inside the ``with`` body so that a
+    configuration error (the SDK raises ``ValueError`` for a missing api_base)
+    is raised within any surrounding :func:`otari_cli._errors.handle_errors`.
+    """
+    client = build_client(config)
+    try:
+        yield client
+    finally:
+        client.close()

otari_cli/_context.py

@@ -0,0 +1,17 @@
+"""Per-invocation application state stored on the Typer context."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from otari_cli.config import OtariConfig
+
+
+@dataclass
+class AppContext:
+    """State shared across the root callback and every subcommand."""
+
+    config: OtariConfig
+    output_json: bool = False

otari_cli/_errors.py

@@ -0,0 +1,67 @@
+"""Mapping of SDK errors to clean CLI messages and process exit codes."""
+
+from __future__ import annotations
+
+import contextlib
+from typing import TYPE_CHECKING
+
+import typer
+from otari.errors import (
+    AuthenticationError,
+    GatewayTimeoutError,
+    InsufficientFundsError,
+    ModelNotFoundError,
+    OtariError,
+    RateLimitError,
+    UpstreamProviderError,
+)
+
+from otari_cli._output import error_console
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+# Exit codes. 1 is the catch-all; the rest let scripts branch on failure mode.
+EXIT_ERROR = 1
+EXIT_AUTH = 2
+EXIT_NOT_FOUND = 3
+EXIT_RATE_LIMIT = 4
+EXIT_FUNDS = 5
+EXIT_UPSTREAM = 6
+
+# Ordered most-specific first; every entry is a distinct OtariError subclass.
+_EXIT_CODES: list[tuple[type[OtariError], int]] = [
+    (AuthenticationError, EXIT_AUTH),
+    (ModelNotFoundError, EXIT_NOT_FOUND),
+    (RateLimitError, EXIT_RATE_LIMIT),
+    (InsufficientFundsError, EXIT_FUNDS),
+    (UpstreamProviderError, EXIT_UPSTREAM),
+    (GatewayTimeoutError, EXIT_UPSTREAM),
+]
+
+
+def exit_code_for(exc: OtariError) -> int:
+    """Return the process exit code for a given otari error."""
+    for exc_type, code in _EXIT_CODES:
+        if isinstance(exc, exc_type):
+            return code
+    return EXIT_ERROR
+
+
+@contextlib.contextmanager
+def handle_errors() -> Iterator[None]:
+    """Convert any :class:`otari.errors.OtariError` into a clean CLI failure.
+
+    The error message is printed to stderr and the process exits with the code
+    from :func:`exit_code_for`.
+    """
+    try:
+        yield
+    except OtariError as exc:
+        error_console().print(f"[bold red]Error:[/] {exc}")
+        raise typer.Exit(exit_code_for(exc)) from exc
+    except ValueError as exc:
+        # The SDK raises ValueError for missing or invalid configuration, e.g.
+        # a missing api_base in self-hosted mode. Surface it without a traceback.
+        error_console().print(f"[bold red]Error:[/] {exc}")
+        raise typer.Exit(EXIT_ERROR) from exc

otari_cli/_output.py

@@ -0,0 +1,91 @@
+"""Rendering helpers: Rich tables and text for humans, JSON for machines.
+
+Every command honors the global ``--json`` flag. Human output uses Rich; JSON
+output is a best-effort conversion of SDK models (pydantic v2 models and
+dataclasses) to plain JSON-serializable data.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+from typing import Any
+
+from rich.console import Console
+from rich.table import Table
+
+_STDOUT = Console()
+_STDERR = Console(stderr=True)
+
+# Cells longer than this are truncated in tables so rows stay readable.
+_MAX_CELL = 60
+
+
+def console() -> Console:
+    """Return the shared stdout console."""
+    return _STDOUT
+
+
+def error_console() -> Console:
+    """Return the shared stderr console (used for error messages)."""
+    return _STDERR
+
+
+def to_jsonable(value: Any) -> Any:
+    """Best-effort conversion of SDK models to JSON-serializable data."""
+    if hasattr(value, "model_dump"):
+        return value.model_dump(mode="json")
+    if isinstance(value, list):
+        return [to_jsonable(item) for item in value]
+    if isinstance(value, dict):
+        return {key: to_jsonable(item) for key, item in value.items()}
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        return dataclasses.asdict(value)
+    return value
+
+
+def print_json(value: Any) -> None:
+    """Print ``value`` as pretty JSON, converting SDK models as needed."""
+    console().print_json(json.dumps(to_jsonable(value), default=str))
+
+
+def _as_record(value: Any) -> dict[str, Any]:
+    """Coerce a single converted item into a flat mapping for table rows."""
+    jsonable = to_jsonable(value)
+    if isinstance(jsonable, dict):
+        return jsonable
+    return {"value": jsonable}
+
+
+def _format_cell(value: Any) -> str:
+    if value is None:
+        return ""
+    text = json.dumps(value, default=str) if isinstance(value, (dict, list)) else str(value)
+    if len(text) > _MAX_CELL:
+        return text[: _MAX_CELL - 1] + "…"
+    return text
+
+
+def render_records(
+    records: list[Any],
+    *,
+    output_json: bool,
+    title: str,
+    empty_message: str,
+    columns: list[str] | None = None,
+) -> None:
+    """Render a list of SDK models as a JSON array or a Rich table."""
+    if output_json:
+        print_json(records)
+        return
+    if not records:
+        console().print(empty_message)
+        return
+    rows = [_as_record(record) for record in records]
+    table_columns = columns or list(rows[0].keys())
+    table = Table(title=title)
+    for column in table_columns:
+        table.add_column(column, overflow="fold")
+    for row in rows:
+        table.add_row(*[_format_cell(row.get(column)) for column in table_columns])
+    console().print(table)

otari_cli/_params.py

@@ -0,0 +1,46 @@
+"""Shared parsing of CLI option strings into structured values."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from typing import Any
+
+import typer
+
+
+def drop_none(**fields: Any) -> dict[str, Any]:
+    """Return only the keyword arguments whose value is not ``None``.
+
+    Used to build control-plane request models from just the options the user
+    provided. Fields the user omits stay out of the model's ``model_fields_set``
+    and are not serialized, so an ``update`` never clears a field the user did
+    not mention (the generated request models serialize explicit ``None``).
+    """
+    return {key: value for key, value in fields.items() if value is not None}
+
+
+def parse_json_object(value: str | None, *, flag: str) -> dict[str, Any] | None:
+    """Parse a JSON-object option (e.g. ``--metadata '{"team": "ml"}'``)."""
+    if value is None:
+        return None
+    try:
+        parsed = json.loads(value)
+    except json.JSONDecodeError as exc:
+        msg = f"{flag} must be valid JSON"
+        raise typer.BadParameter(msg) from exc
+    if not isinstance(parsed, dict):
+        msg = f"{flag} must be a JSON object"
+        raise typer.BadParameter(msg)
+    return parsed
+
+
+def parse_datetime(value: str | None, *, flag: str) -> datetime | None:
+    """Parse an ISO-8601 date/time option."""
+    if value is None:
+        return None
+    try:
+        return datetime.fromisoformat(value)
+    except ValueError as exc:
+        msg = f"{flag} must be an ISO-8601 date/time (e.g. 2026-01-31 or 2026-01-31T12:00:00)"
+        raise typer.BadParameter(msg) from exc

otari_cli/cli.py

@@ -0,0 +1,103 @@
+"""Root Typer application: global options and command wiring."""
+
+from __future__ import annotations
+
+import typer
+
+from otari_cli import __version__
+from otari_cli._context import AppContext
+from otari_cli.commands import (
+    batches,
+    budgets,
+    completion,
+    embedding,
+    health,
+    keys,
+    message,
+    models,
+    moderation,
+    pricing,
+    rerank,
+    response,
+    usage,
+    users,
+)
+from otari_cli.config import OtariConfig
+
+app = typer.Typer(
+    name="otari",
+    help="Command-line interface for the otari LLM gateway and platform.",
+    no_args_is_help=True,
+    add_completion=True,
+)
+
+# Generation / inference commands.
+app.command("completion")(completion.completion)
+app.command("response")(response.response)
+app.command("message")(message.message)
+app.command("embedding")(embedding.embedding)
+app.command("moderation")(moderation.moderation)
+app.command("rerank")(rerank.rerank)
+app.command("models")(models.models)
+app.command("health")(health.health)
+app.add_typer(batches.app, name="batches")
+
+# Control-plane (management) command groups.
+app.add_typer(keys.app, name="keys")
+app.add_typer(users.app, name="users")
+app.add_typer(budgets.app, name="budgets")
+app.add_typer(pricing.app, name="pricing")
+app.add_typer(usage.app, name="usage")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit
+
+
+@app.callback()
+def main_callback(
+    ctx: typer.Context,
+    api_base: str | None = typer.Option(
+        None, "--api-base", help="Gateway base URL (env: GATEWAY_API_BASE)."
+    ),
+    api_key: str | None = typer.Option(
+        None, "--api-key", help="Self-hosted API key (env: GATEWAY_API_KEY)."
+    ),
+    token: str | None = typer.Option(
+        None, "--token", help="Platform token (env: OTARI_AI_TOKEN)."
+    ),
+    admin_key: str | None = typer.Option(
+        None, "--admin-key", help="Admin key for control-plane commands (env: GATEWAY_ADMIN_KEY)."
+    ),
+    output_json: bool = typer.Option(
+        False, "--json", help="Emit JSON instead of human-readable output."
+    ),
+    version: bool = typer.Option(  # noqa: ARG001  (consumed by the eager callback)
+        False,
+        "--version",
+        help="Show the otari-cli version and exit.",
+        is_eager=True,
+        callback=_version_callback,
+    ),
+) -> None:
+    """Resolve connection settings and store shared state on the context."""
+    ctx.obj = AppContext(
+        config=OtariConfig.resolve(
+            api_base=api_base,
+            api_key=api_key,
+            token=token,
+            admin_key=admin_key,
+        ),
+        output_json=output_json,
+    )
+
+
+def main() -> None:
+    """Console-script entry point (``otari``)."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

otari_cli/commands/__init__.py

@@ -0,0 +1,6 @@
+"""CLI command groups.
+
+Each module exposes either a command function (``completion``, ``models``,
+``health``) or a Typer sub-app (``keys``, ``usage``) that
+:mod:`otari_cli.cli` wires onto the root application.
+"""

otari_cli/commands/batches.py

@@ -0,0 +1,153 @@
+"""``otari batches`` - manage batch jobs.
+
+The provider (for example ``openai``) is required to retrieve, cancel, list, or
+fetch results, mirroring the SDK. ``create`` reads a JSONL request file where
+each line is a JSON object with ``custom_id`` and ``body`` keys.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path  # noqa: TC003  (Typer resolves the Path annotation at runtime)
+from typing import TYPE_CHECKING, Any, cast
+
+import typer
+
+from otari_cli import _client
+from otari_cli._errors import handle_errors
+from otari_cli._output import console, print_json, render_records
+from otari_cli._params import parse_json_object
+
+if TYPE_CHECKING:
+    from otari import CreateBatchParams, ListBatchesOptions
+
+    from otari_cli._context import AppContext
+
+app = typer.Typer(
+    name="batches",
+    help="Create and manage batch jobs.",
+    no_args_is_help=True,
+)
+
+
+def _load_requests(path: Path) -> list[dict[str, Any]]:
+    requests: list[dict[str, Any]] = []
+    for lineno, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
+        stripped = line.strip()
+        if not stripped:
+            continue
+        try:
+            entry = json.loads(stripped)
+        except json.JSONDecodeError as exc:
+            msg = f"--input line {lineno} is not valid JSON"
+            raise typer.BadParameter(msg) from exc
+        if not isinstance(entry, dict) or "custom_id" not in entry or "body" not in entry:
+            msg = f"--input line {lineno} must be a JSON object with 'custom_id' and 'body'"
+            raise typer.BadParameter(msg)
+        requests.append({"custom_id": entry["custom_id"], "body": entry["body"]})
+    if not requests:
+        msg = "--input contained no request lines"
+        raise typer.BadParameter(msg)
+    return requests
+
+
+@app.command("create")
+def create_batch(
+    ctx: typer.Context,
+    input_file: Path = typer.Option(
+        ...,
+        "--input",
+        "-i",
+        exists=True,
+        readable=True,
+        dir_okay=False,
+        help="JSONL file of requests, one {custom_id, body} object per line.",
+    ),
+    model: str = typer.Option(..., "--model", "-m", help="Model id, e.g. 'openai:gpt-4o-mini'."),
+    completion_window: str | None = typer.Option(None, "--completion-window", help="Completion window, e.g. '24h'."),
+    metadata: str | None = typer.Option(None, "--metadata", help="Metadata as a JSON object."),
+) -> None:
+    """Create a batch job from a JSONL request file."""
+    app_ctx: AppContext = ctx.obj
+    params: dict[str, Any] = {"model": model, "requests": _load_requests(input_file)}
+    if completion_window is not None:
+        params["completion_window"] = completion_window
+    parsed_metadata = parse_json_object(metadata, flag="--metadata")
+    if parsed_metadata is not None:
+        params["metadata"] = parsed_metadata
+    with handle_errors(), _client.session(app_ctx.config) as client:
+        result = client.create_batch(cast("CreateBatchParams", params))
+    print_json(result)
+
+
+@app.command("retrieve")
+def retrieve_batch(
+    ctx: typer.Context,
+    batch_id: str = typer.Argument(..., help="Identifier of the batch."),
+    provider: str = typer.Option(..., "--provider", help="Provider that owns the batch, e.g. 'openai'."),
+) -> None:
+    """Retrieve the status of a batch job."""
+    app_ctx: AppContext = ctx.obj
+    with handle_errors(), _client.session(app_ctx.config) as client:
+        result = client.retrieve_batch(batch_id, provider)
+    print_json(result)
+
+
+@app.command("list")
+def list_batches(
+    ctx: typer.Context,
+    provider: str = typer.Option(..., "--provider", help="Provider to list batches for, e.g. 'openai'."),
+    after: str | None = typer.Option(None, "--after", help="Return batches after this id."),
+    limit: int | None = typer.Option(None, "--limit", help="Maximum number of batches to return."),
+) -> None:
+    """List batch jobs for a provider."""
+    app_ctx: AppContext = ctx.obj
+    options: dict[str, Any] = {}
+    if after is not None:
+        options["after"] = after
+    if limit is not None:
+        options["limit"] = limit
+    with handle_errors(), _client.session(app_ctx.config) as client:
+        result = client.list_batches(provider, cast("ListBatchesOptions", options))
+    render_records(
+        list(result),
+        output_json=app_ctx.output_json,
+        title="Batches",
+        empty_message="No batches found.",
+    )
+
+
+@app.command("cancel")
+def cancel_batch(
+    ctx: typer.Context,
+    batch_id: str = typer.Argument(..., help="Identifier of the batch to cancel."),
+    provider: str = typer.Option(..., "--provider", help="Provider that owns the batch, e.g. 'openai'."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip the confirmation prompt."),
+) -> None:
+    """Cancel a batch job."""
+    app_ctx: AppContext = ctx.obj
+    if not yes:
+        typer.confirm(f"Cancel batch {batch_id!r}?", abort=True)
+    with handle_errors(), _client.session(app_ctx.config) as client:
+        result = client.cancel_batch(batch_id, provider)
+    print_json(result)
+
+
+@app.command("results")
+def batch_results(
+    ctx: typer.Context,
+    batch_id: str = typer.Argument(..., help="Identifier of the completed batch."),
+    provider: str = typer.Option(..., "--provider", help="Provider that owns the batch, e.g. 'openai'."),
+) -> None:
+    """Retrieve the results of a completed batch job."""
+    app_ctx: AppContext = ctx.obj
+    with handle_errors(), _client.session(app_ctx.config) as client:
+        result = client.retrieve_batch_results(batch_id, provider)
+    if app_ctx.output_json:
+        print_json(result)
+        return
+    items = getattr(result, "results", None) or []
+    if not items:
+        console().print("No results in batch.")
+        return
+    render_records(list(items), output_json=False, title="Batch results", empty_message="No results in batch.")

otari_cli/commands/budgets.py

@@ -0,0 +1,96 @@
+"""``otari budgets`` - manage spending budgets (control plane).
+
+Requires an admin credential and a self-hosted/standalone gateway.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import typer
+from otari._client import CreateBudgetRequest, UpdateBudgetRequest
+
+from otari_cli import _client
+from otari_cli._errors import handle_errors
+from otari_cli._output import console, print_json, render_records
+from otari_cli._params import drop_none
+
+if TYPE_CHECKING:
+    from otari_cli._context import AppContext
+
+app = typer.Typer(
+    name="budgets",
+    help="Manage spending budgets (admin / self-hosted only).",
+    no_args_is_help=True,
+)
+
+
+@app.command("list")
+def list_budgets(
+    ctx: typer.Context,
+    skip: int | None = typer.Option(None, "--skip", help="Number of budgets to skip."),
+    limit: int | None = typer.Option(None, "--limit", help="Maximum number of budgets to return."),
+) -> None:
+    """List budgets."""
+    app_ctx: AppContext = ctx.obj
+    with handle_errors(), _client.session(app_ctx.config) as client:
+        result = client.control_plane.budgets.list(skip=skip, limit=limit)
+    render_records(list(result), output_json=app_ctx.output_json, title="Budgets", empty_message="No budgets found.")
+
+
+@app.command("get")
+def get_budget(
+    ctx: typer.Context,
+    budget_id: str = typer.Argument(..., help="Identifier of the budget."),
+) -> None:
+    """Show details for a single budget."""
+    app_ctx: AppContext = ctx.obj
+    with handle_errors(), _client.session(app_ctx.config) as client:
+        result = client.control_plane.budgets.get(budget_id)
+    print_json(result)
+
+
+@app.command("create")
+def create_budget(
+    ctx: typer.Context,
+    max_budget: float = typer.Option(..., "--max-budget", help="Maximum spending limit."),
+    duration_sec: int | None = typer.Option(
+        None, "--duration-sec", help="Budget window in seconds (e.g. 86400 for daily)."
+    ),
+) -> None:
+    """Create a budget."""
+    app_ctx: AppContext = ctx.obj
+    request = CreateBudgetRequest(max_budget=max_budget, **drop_none(budget_duration_sec=duration_sec))
+    with handle_errors(), _client.session(app_ctx.config) as client:
+        result = client.control_plane.budgets.create(request)
+    print_json(result)
+
+
+@app.command("update")
+def update_budget(
+    ctx: typer.Context,
+    budget_id: str = typer.Argument(..., help="Identifier of the budget to update."),
+    max_budget: float | None = typer.Option(None, "--max-budget", help="New maximum spending limit."),
+    duration_sec: int | None = typer.Option(None, "--duration-sec", help="New budget window in seconds."),
+) -> None:
+    """Update a budget. Only the provided fields are changed."""
+    app_ctx: AppContext = ctx.obj
+    request = UpdateBudgetRequest(**drop_none(max_budget=max_budget, budget_duration_sec=duration_sec))
+    with handle_errors(), _client.session(app_ctx.config) as client:
+        result = client.control_plane.budgets.update(budget_id, request)
+    print_json(result)
+
+
+@app.command("delete")
+def delete_budget(
+    ctx: typer.Context,
+    budget_id: str = typer.Argument(..., help="Identifier of the budget to delete."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip the confirmation prompt."),
+) -> None:
+    """Delete a budget."""
+    app_ctx: AppContext = ctx.obj
+    if not yes:
+        typer.confirm(f"Delete budget {budget_id!r}?", abort=True)
+    with handle_errors(), _client.session(app_ctx.config) as client:
+        client.control_plane.budgets.delete(budget_id)
+    console().print(f"[bold green]Deleted[/] budget {budget_id!r}.")