outo-models-cli 0.1.0__py3-none-any.whl

outo_models_cli/__init__.py

@@ -0,0 +1,19 @@
+"""`outo-models-cli` — the user-facing command-line client for self-hosted outo-models servers.
+
+Mirrors the surface area of `huggingface-cli` so users familiar with the Hub
+can drive a self-hosted server without learning a new vocabulary:
+
+    * `omc auth login --server ...` stores a PAT per server.
+    * `omc repo create / delete / list` manage repositories.
+    * `omc ls <owner>/<name>` lists a directory at a revision.
+    * `omc download <owner>/<name>` streams a repository (resumable).
+    * `omc upload <owner>/<name> <path>` ships one or many files.
+
+The package is intentionally tiny: it owns the user-visible surface, nothing
+else. The server itself ships separately as `outo-models`.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

outo_models_cli/__main__.py

@@ -0,0 +1,6 @@
+"""`python -m outo_models_cli` entry point."""
+
+from outo_models_cli.main import cli_main
+
+if __name__ == "__main__":
+    cli_main()

outo_models_cli/api/__init__.py

@@ -0,0 +1,223 @@
+"""Typed client for the public outo-models REST API.
+
+Each public method in this package is a thin wrapper around one HTTP
+call. The shared logic — error mapping, transport-layer wrapping, auth
+header insertion — lives in `http.build_client`. Command modules never
+touch `httpx` directly so a wire-format change (renamed field, new
+envelope) only touches one file.
+
+The methods are *synchronous* because the CLI commands that use them
+(single-shot ops like `repo create`, `repo list`, `auth whoami`, `ls`)
+are short-lived and benefit from the simpler control flow. The
+streaming download command uses `http.build_async_client` directly
+because parallelism is the whole point of that command.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from outo_models_cli.errors import (
+    BadResponseError,
+    map_transport_error,
+)
+from outo_models_cli.http import build_client
+
+# ---------------------------------------------------------------------------
+# Dataclasses — response shapes, pinned for the wire contract
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class WhoAmI:
+    """Result of `GET /api/auth/me`."""
+
+    username: str
+    role: str
+    server: str
+
+
+@dataclass(frozen=True, slots=True)
+class RepoSummary:
+    """Subset of `GET /api/repos` / `POST /api/repos` payloads.
+
+    Fields not needed by the CLI (e.g. `id`, timestamps) are dropped on
+    the server's JSON payload so the response stays minimal. Commands
+    that need the full record should call `get_repo()`.
+    """
+
+    name: str
+    kind: str
+    visibility: str
+    description: str | None
+    size_bytes: int
+    owner: str
+    clone_url: str
+
+
+@dataclass(frozen=True, slots=True)
+class RepoDetail(RepoSummary):
+    """`GET /api/repos/{owner}/{name}` payload."""
+
+    downloads_count: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class FileEntry:
+    """One row in `GET /api/repos/{owner}/{name}/files`."""
+
+    name: str
+    path: str
+    kind: str  # "file" | "dir"
+    size_bytes: int | None
+
+
+@dataclass(frozen=True, slots=True)
+class UploadResult:
+    """Server's response to a successful `POST .../upload`."""
+
+    commit_sha: str
+    files: list[str]
+    message: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# Shared JSON unwrap + error funnel
+# ---------------------------------------------------------------------------
+
+
+def unwrap(response: httpx.Response) -> dict[str, Any]:
+    """Parse a JSON object body or raise a clean error."""
+    if response.status_code == 204 or not response.content:
+        return {}
+    try:
+        payload: Any = response.json()
+    except ValueError as exc:
+        raise BadResponseError("The server returned a non-JSON response.") from exc
+    if not isinstance(payload, dict):
+        raise BadResponseError("The server returned an unexpected response shape.")
+    return payload
+
+
+def send(client: httpx.Client, method: str, path: str, **kwargs: Any) -> httpx.Response:
+    """Issue `method path` and translate transport failures."""
+    try:
+        return client.request(method, path, **kwargs)
+    except httpx.HTTPError as exc:
+        raise map_transport_error(exc) from exc
+
+
+# ---------------------------------------------------------------------------
+# Repos helpers (shared by submodules)
+# ---------------------------------------------------------------------------
+
+
+def summary_from(payload: dict[str, Any]) -> RepoSummary:
+    """Parse a `/api/repos` row into a `RepoSummary`."""
+    owner = payload.get("owner", "")
+    description = payload.get("description")
+    return RepoSummary(
+        name=str(payload.get("name", "")),
+        kind=str(payload.get("kind", "")),
+        visibility=str(payload.get("visibility", "")),
+        description=None if description is None else str(description),
+        size_bytes=int(payload.get("size_bytes", 0)),
+        owner=str(owner),
+        clone_url=str(payload.get("clone_url", "")),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Facade — issue calls against a fresh `httpx.Client`
+# ---------------------------------------------------------------------------
+
+
+def with_client(
+    base_url: str,
+    token: str,
+    *,
+    transport: httpx.BaseTransport | None = None,
+) -> httpx.Client:
+    """Construct a short-lived client for the caller to use as a context.
+
+    `transport=` is forwarded so tests can inject an `httpx.MockTransport`
+    (or a `respx` router) without monkeypatching — same convention as
+    the server's admin client.
+    """
+    kwargs: dict[str, Any] = {}
+    if transport is not None:
+        kwargs["transport"] = transport
+    return build_client(base_url, token, **kwargs)
+
+
+# ---------------------------------------------------------------------------
+# Display-name helper used by `upload`
+# ---------------------------------------------------------------------------
+
+
+def display_filename(path_str: str, *, file_root: Path | None, idx: int) -> str:
+    """Compute the filename sent in the multipart part.
+
+    For file uploads (no `file_root`), the basename is sent verbatim.
+    For folder uploads, the relative path under `file_root` is sent so
+    the server stores `dir/file.txt` rather than `file.txt`.
+    """
+    name = Path(path_str).name
+    if file_root is None:
+        return name
+    try:
+        rel = Path(path_str).resolve().relative_to(file_root.resolve())
+    except ValueError:
+        # Fallback to basename if the file isn't actually under `file_root`.
+        # The server will still store it under `path_in_repo`, so the
+        # upload cannot silently land in the wrong place — it just
+        # degrades to a flat listing.
+        return name
+    rel_str = rel.as_posix()
+    return rel_str or name or f"file-{idx}"
+
+
+# ---------------------------------------------------------------------------
+# Submodule re-exports
+# ---------------------------------------------------------------------------
+# Imported last so the dataclasses defined above are visible to the
+# submodules' `from outo_models_cli.api import ...` statements. Call
+# sites can write `api.me(...)` instead of `api.auth.me(...)`.
+
+from outo_models_cli.api.auth import me  # noqa: E402
+from outo_models_cli.api.repos import (  # noqa: E402
+    create_repo,
+    delete_repo,
+    get_repo,
+    list_files,
+    list_repos,
+    resolve_url,
+    walk_repo,
+)
+from outo_models_cli.api.upload import upload  # noqa: E402
+
+__all__ = [
+    "FileEntry",
+    "RepoDetail",
+    "RepoSummary",
+    "UploadResult",
+    "WhoAmI",
+    "create_repo",
+    "delete_repo",
+    "display_filename",
+    "get_repo",
+    "list_files",
+    "list_repos",
+    "me",
+    "resolve_url",
+    "send",
+    "summary_from",
+    "unwrap",
+    "upload",
+    "walk_repo",
+    "with_client",
+]

outo_models_cli/api/auth.py

@@ -0,0 +1,27 @@
+"""`GET /api/auth/me` — verify the bearer token."""
+
+from __future__ import annotations
+
+import httpx
+
+from outo_models_cli.api import WhoAmI, send, unwrap
+from outo_models_cli.errors import BadResponseError, map_response_error
+
+
+def me(client: httpx.Client) -> WhoAmI:
+    """Return the authenticated user's identity.
+
+    Raises `AuthInvalidError` if the token is rejected (HTTP 401).
+    """
+    response = send(client, "GET", "/api/auth/me")
+    if response.status_code >= 400:
+        raise map_response_error(response)
+    payload = unwrap(response)
+    username = payload.get("username")
+    role = payload.get("role")
+    if not isinstance(username, str) or not isinstance(role, str):
+        raise BadResponseError("`/api/auth/me` returned an unexpected payload shape.")
+    return WhoAmI(username=username, role=role, server=str(client.base_url))
+
+
+__all__ = ["me"]

outo_models_cli/api/repos.py

@@ -0,0 +1,189 @@
+"""Repo CRUD + tree listing over the public REST API."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from outo_models_cli.api import (
+    FileEntry,
+    RepoDetail,
+    RepoSummary,
+    send,
+    summary_from,
+    unwrap,
+)
+from outo_models_cli.errors import BadResponseError, map_response_error
+
+
+def create_repo(
+    client: httpx.Client,
+    *,
+    name: str,
+    kind: str,
+    visibility: str,
+    description: str | None,
+) -> RepoSummary:
+    """`POST /api/repos` — returns the new repo summary."""
+    body: dict[str, Any] = {
+        "name": name,
+        "kind": kind,
+        "visibility": visibility,
+        "description": description,
+    }
+    response = send(client, "POST", "/api/repos", json=body)
+    if response.status_code >= 400:
+        raise map_response_error(response)
+    return summary_from(unwrap(response))
+
+
+def delete_repo(client: httpx.Client, *, owner: str, name: str, kind: str) -> None:
+    """`DELETE /api/repos/{owner}/{name}?kind=` — no body."""
+    response = send(client, "DELETE", f"/api/repos/{owner}/{name}", params={"kind": kind})
+    if response.status_code >= 400:
+        raise map_response_error(response)
+
+
+def list_repos(
+    client: httpx.Client,
+    *,
+    kind: str | None = None,
+    owner: str | None = None,
+) -> list[RepoSummary]:
+    """`GET /api/repos` — paginated server-side; client returns the full list."""
+    params: dict[str, str] = {}
+    if kind:
+        params["kind"] = kind
+    if owner:
+        params["owner"] = owner
+    response = send(client, "GET", "/api/repos", params=params)
+    if response.status_code >= 400:
+        raise map_response_error(response)
+    try:
+        rows: Any = response.json()
+    except ValueError as exc:
+        raise BadResponseError("`/api/repos` returned a non-JSON response.") from exc
+    if not isinstance(rows, list):
+        raise BadResponseError("`/api/repos` returned a non-list response.")
+    return [summary_from(item) for item in rows if isinstance(item, dict)]
+
+
+def get_repo(client: httpx.Client, *, owner: str, name: str) -> RepoDetail:
+    """`GET /api/repos/{owner}/{name}` — full detail payload."""
+    response = send(client, "GET", f"/api/repos/{owner}/{name}")
+    if response.status_code >= 400:
+        raise map_response_error(response)
+    payload = unwrap(response)
+    summary = summary_from(payload)
+    return RepoDetail(
+        name=summary.name,
+        kind=summary.kind,
+        visibility=summary.visibility,
+        description=summary.description,
+        size_bytes=summary.size_bytes,
+        owner=summary.owner,
+        clone_url=summary.clone_url,
+        downloads_count=int(payload.get("downloads_count", 0)),
+    )
+
+
+def list_files(
+    client: httpx.Client,
+    *,
+    owner: str,
+    name: str,
+    path: str = "",
+    revision: str | None = None,
+) -> list[FileEntry]:
+    """`GET /api/repos/{owner}/{name}/files?path=&revision=`.
+
+    The server may ignore the `revision` parameter (the current
+    implementation only lists the default branch tip). When it does
+    the response is still well-formed; this client simply forwards the
+    flag verbatim so a future revision-aware server picks it up without
+    a CLI release.
+    """
+    params: dict[str, str] = {}
+    if path:
+        params["path"] = path
+    if revision:
+        params["revision"] = revision
+    response = send(
+        client,
+        "GET",
+        f"/api/repos/{owner}/{name}/files",
+        params=params,
+    )
+    if response.status_code >= 400:
+        raise map_response_error(response)
+    payload = unwrap(response)
+    rows = payload.get("entries", [])
+    if not isinstance(rows, list):
+        raise BadResponseError("`/files` returned a malformed `entries` field.")
+    entries: list[FileEntry] = []
+    for row in rows:
+        if not isinstance(row, dict):
+            continue
+        size = row.get("size_bytes")
+        entries.append(
+            FileEntry(
+                name=str(row.get("name", "")),
+                path=str(row.get("path", "")),
+                kind=str(row.get("kind", "")),
+                size_bytes=int(size) if isinstance(size, (int, float)) else None,
+            )
+        )
+    return entries
+
+
+def walk_repo(
+    client: httpx.Client,
+    *,
+    owner: str,
+    name: str,
+    revision: str | None = None,
+    include: list[str] | None = None,
+    exclude: list[str] | None = None,
+) -> list[FileEntry]:
+    """Recursively enumerate every file under a repo."""
+    from outo_models_cli.matchers import passes
+
+    out: list[FileEntry] = []
+
+    def visit(directory: str) -> None:
+        rows = list_files(client, owner=owner, name=name, path=directory, revision=revision)
+        for entry in rows:
+            if entry.kind == "dir":
+                visit(entry.path)
+            elif entry.kind == "file" and passes(entry.path, include=include, exclude=exclude):
+                out.append(entry)
+
+    visit("")
+    return out
+
+
+def resolve_url(*, owner: str, name: str, revision: str, path: str) -> str:
+    """Build the path-component-only URL for a raw file resolution.
+
+    Returned as a string (no client needed) so the download command can
+    hand it to its own `httpx.AsyncClient` and stream the body directly.
+    """
+    from urllib.parse import quote
+
+    encoded_owner = quote(owner, safe="")
+    encoded_name = quote(name, safe="")
+    encoded_revision = quote(revision, safe="")
+    encoded_path = quote(path, safe="/")
+    return f"/{encoded_owner}/{encoded_name}/resolve/{encoded_revision}/{encoded_path}"
+
+
+__all__ = [
+    "create_repo",
+    "delete_repo",
+    "get_repo",
+    "list_files",
+    "list_repos",
+    "resolve_url",
+    "walk_repo",
+]

outo_models_cli/api/upload.py

@@ -0,0 +1,107 @@
+"""Multipart upload via `POST /api/repos/{owner}/{name}/upload`."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+from typing import BinaryIO
+
+import httpx
+
+from outo_models_cli.api import (
+    UploadResult,
+    display_filename,
+    send,
+    unwrap,
+)
+from outo_models_cli.errors import BadResponseError, map_response_error
+
+
+def upload(
+    client: httpx.Client,
+    *,
+    owner: str,
+    name: str,
+    files: Iterable[Path],
+    path_in_repo: str = "",
+    message: str | None = None,
+    file_root: Path | None = None,
+    file_handles: Iterable[BinaryIO] | None = None,
+) -> UploadResult:
+    """Multipart upload of one or many files.
+
+    Args:
+        owner / name: Target repo coordinates.
+        files: Paths to local files. The filename of each multipart part
+            is the *basename* of the path, with the in-repo `path` prefix
+            applied by the server using the multipart `path` field.
+        path_in_repo: Subdirectory inside the repo where files land
+            (server applies it to every filename).
+        message: Optional commit message.
+        file_root: When set, the in-repo subpath is computed relative to
+            this root (used for folder uploads where the user wants
+            `dir/file.txt` rather than `file.txt` inside the destination).
+        file_handles: Optional iterable of pre-opened binary handles; the
+            caller is responsible for closing them. Pass `None` to have
+            this function open the paths itself.
+
+    The caller must pre-validate that no single file exceeds
+    100 MiB; this function trusts the caller and does not re-check
+    (re-checking after opening the file would mean reading the file's
+    bytes into Python just to count them).
+    """
+    opens_handles = file_handles is None
+    opened: list[BinaryIO] = []
+    try:
+        if opens_handles:
+            opened = [f.open("rb") for f in files]
+            handles = opened
+        elif file_handles is not None:
+            handles = list(file_handles)
+        else:
+            handles = []
+
+        multipart_files: list[tuple[str, tuple[str, BinaryIO, str]]] = []
+        for idx, handle in enumerate(handles):
+            filename = handle.name
+            display_name = display_filename(filename, file_root=file_root, idx=idx)
+            multipart_files.append(
+                ("files", (display_name, handle, "application/octet-stream")),
+            )
+
+        # httpx treats `data=[(name, value)]` as a raw (name, value) iterator,
+        # NOT as multipart form fields. Build a dict so the keys become
+        # `Content-Disposition: form-data; name=...` parts of the envelope.
+        fields: dict[str, str] = {}
+        if path_in_repo:
+            fields["path"] = path_in_repo
+        if message:
+            fields["message"] = message
+
+        response = send(
+            client,
+            "POST",
+            f"/api/repos/{owner}/{name}/upload",
+            files=multipart_files,
+            data=fields,
+        )
+        if response.status_code >= 400:
+            raise map_response_error(response)
+        payload = unwrap(response)
+        commit_sha = payload.get("commit_sha")
+        files_acked = payload.get("files", [])
+        if not isinstance(commit_sha, str) or not commit_sha:
+            raise BadResponseError("`/upload` response is missing `commit_sha`.")
+        if not isinstance(files_acked, list):
+            files_acked = []
+        return UploadResult(
+            commit_sha=commit_sha,
+            files=[str(name) for name in files_acked],
+            message=(str(payload["message"]) if isinstance(payload.get("message"), str) else None),
+        )
+    finally:
+        for handle in opened:
+            handle.close()
+
+
+__all__ = ["upload"]

outo_models_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""`omc auth ...` — manage stored credentials."""