admatrix-client 0.1.0__py3-none-any.whl

admatrix_client/__init__.py

@@ -0,0 +1,27 @@
+from .auth import APIKeyAuth, AuthProvider, RuntimeJWTAuth
+from .client import AdMatrixClient
+from .errors import (
+    AdMatrixAPIError,
+    AdMatrixError,
+    AdMatrixTimeoutError,
+    AdMatrixTransportError,
+    AdMatrixValidationError,
+)
+from .types import Generation, Model, ModelSchema, Score, UploadedAsset
+
+__all__ = [
+    "APIKeyAuth",
+    "AdMatrixAPIError",
+    "AdMatrixClient",
+    "AdMatrixError",
+    "AdMatrixTimeoutError",
+    "AdMatrixTransportError",
+    "AdMatrixValidationError",
+    "AuthProvider",
+    "Generation",
+    "Model",
+    "ModelSchema",
+    "RuntimeJWTAuth",
+    "Score",
+    "UploadedAsset",
+]

admatrix_client/auth.py

@@ -0,0 +1,223 @@
+from __future__ import annotations
+
+import ipaddress
+import json
+import os
+import stat
+import tempfile
+from collections.abc import Callable, Mapping
+from pathlib import Path
+from typing import Protocol
+from urllib.parse import urlparse
+
+import keyring
+
+
+class AuthProvider(Protocol):
+    def headers(self) -> Mapping[str, str]: ...
+
+
+class APIKeyAuth:
+    def __init__(self, api_key: str) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._api_key = api_key
+
+    def headers(self) -> Mapping[str, str]:
+        return {"X-API-KEY": self._api_key}
+
+
+class RuntimeJWTAuth:
+    def __init__(self, token_supplier: Callable[[], str]) -> None:
+        self._token_supplier = token_supplier
+
+    def headers(self) -> Mapping[str, str]:
+        token = self._token_supplier()
+        if not token:
+            raise ValueError("runtime JWT supplier returned an empty token")
+        return {"Authorization": f"Bearer {token}"}
+
+
+def validate_api_key_transport(base_url: str) -> None:
+    """Reject plaintext API-Key transport except on loopback hosts."""
+    parsed = urlparse(base_url)
+    hostname = parsed.hostname
+    if parsed.scheme == "https" and hostname:
+        return
+    if parsed.scheme == "http" and hostname:
+        is_loopback = hostname == "localhost" or hostname.endswith(".localhost")
+        if not is_loopback:
+            try:
+                is_loopback = ipaddress.ip_address(hostname).is_loopback
+            except ValueError:
+                is_loopback = False
+        if is_loopback:
+            return
+    raise ValueError(
+        "API Key endpoints must use HTTPS; only localhost and loopback addresses may use HTTP"
+    )
+
+
+class KeyringBackend(Protocol):
+    def get_password(self, service: str, username: str) -> str | None: ...
+
+    def set_password(self, service: str, username: str, value: str) -> None: ...
+
+    def delete_password(self, service: str, username: str) -> None: ...
+
+
+class CredentialStore:
+    service = "yc-admatrix"
+    username = "api-key"
+
+    def __init__(
+        self,
+        *,
+        path: Path | None = None,
+        keyring_backend: KeyringBackend | None = None,
+    ) -> None:
+        configured_path = os.getenv("YC_CREDENTIAL_FILE")
+        self.path = path or (
+            Path(configured_path)
+            if configured_path
+            else Path.home() / ".config" / "yc" / "credentials.json"
+        )
+        self._keyring = keyring_backend or keyring
+
+    def save(self, api_key: str) -> str:
+        if not api_key:
+            raise ValueError("API Key cannot be empty")
+        try:
+            self._keyring.set_password(self.service, self.username, api_key)
+            self._delete_file()
+            return "keyring"
+        except Exception:
+            try:
+                existing = self._keyring.get_password(self.service, self.username)
+            except Exception:
+                existing = None
+            if existing == api_key:
+                self._delete_file()
+                return "keyring"
+            if existing:
+                try:
+                    self._keyring.delete_password(self.service, self.username)
+                except Exception as delete_error:
+                    raise OSError(
+                        "cannot replace the existing keyring API Key; "
+                        "the old credential is still configured"
+                    ) from delete_error
+                try:
+                    remaining = self._keyring.get_password(self.service, self.username)
+                except Exception as verify_error:
+                    raise OSError(
+                        "cannot verify removal of the existing keyring API Key"
+                    ) from verify_error
+                if remaining:
+                    raise OSError(
+                        "the existing keyring API Key could not be removed"
+                    ) from None
+            self._save_file(api_key)
+            return "file"
+
+    def load(self) -> str | None:
+        # A file only remains after keyring storage failed. Keep that fallback
+        # authoritative so a temporarily unavailable keyring cannot later
+        # resurrect an older credential.
+        file_value = self._load_file()
+        if file_value:
+            return file_value
+        try:
+            value = self._keyring.get_password(self.service, self.username)
+            if value:
+                return value
+        except Exception:
+            pass
+        return None
+
+    def source(self) -> str | None:
+        if self._load_file():
+            return "file"
+        try:
+            if self._keyring.get_password(self.service, self.username):
+                return "keyring"
+        except Exception:
+            pass
+        return None
+
+    def delete(self) -> None:
+        keyring_error: Exception | None = None
+        try:
+            self._keyring.delete_password(self.service, self.username)
+        except Exception as error:
+            try:
+                remaining = self._keyring.get_password(self.service, self.username)
+            except Exception:
+                keyring_error = error
+            else:
+                if remaining:
+                    keyring_error = error
+        self._delete_file()
+        if keyring_error is not None:
+            raise OSError(
+                "cannot remove or verify removal of the keyring API Key"
+            ) from keyring_error
+
+    def _save_file(self, api_key: str) -> None:
+        self.path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+        descriptor, temporary_name = tempfile.mkstemp(
+            prefix=f".{self.path.name}.",
+            suffix=".tmp",
+            dir=self.path.parent,
+        )
+        temporary = Path(temporary_name)
+        try:
+            with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+                descriptor = -1
+                json.dump({"api_key": api_key}, handle)
+                handle.write("\n")
+            os.chmod(temporary, 0o600)
+            os.replace(temporary, self.path)
+            os.chmod(self.path, 0o600)
+        finally:
+            if descriptor >= 0:
+                os.close(descriptor)
+            if temporary.exists():
+                temporary.unlink()
+
+    def _load_file(self) -> str | None:
+        try:
+            file_stat = self.path.lstat()
+        except FileNotFoundError:
+            return None
+        if os.name == "posix":
+            mode = stat.S_IMODE(file_stat.st_mode)
+            if stat.S_ISLNK(file_stat.st_mode) or mode & 0o077:
+                raise PermissionError(
+                    f"credential file {self.path} must be an owner-only 0600 file"
+                )
+            if hasattr(os, "getuid") and file_stat.st_uid != os.getuid():
+                raise PermissionError(
+                    f"credential file {self.path} must be owned by the current user"
+                )
+        try:
+            payload = json.loads(self.path.read_text(encoding="utf-8"))
+        except (OSError, ValueError, TypeError):
+            return None
+        value = payload.get("api_key")
+        return value if isinstance(value, str) and value else None
+
+    def _delete_file(self) -> None:
+        try:
+            self.path.unlink()
+        except FileNotFoundError:
+            pass
+
+
+def resolve_api_key(store: CredentialStore | None = None) -> tuple[str | None, str | None]:
+    environment = os.getenv("YC_API_KEY")
+    if environment:
+        return environment, "environment"
+    credential_store = store or CredentialStore()
+    value = credential_store.load()
+    return value, credential_store.source() if value else None

admatrix_client/client.py

@@ -0,0 +1,315 @@
+from __future__ import annotations
+
+import mimetypes
+import time
+from pathlib import Path
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+import jsonschema
+
+from .auth import APIKeyAuth, AuthProvider, validate_api_key_transport
+from .errors import (
+    AdMatrixAPIError,
+    AdMatrixTimeoutError,
+    AdMatrixTransportError,
+    AdMatrixValidationError,
+)
+from .types import Generation, JsonObject, Model, ModelSchema, Score, UploadedAsset
+
+_TERMINAL_GENERATION_STATUSES = {
+    "completed",
+    "partial",
+    "failed",
+    "error",
+    "cancelled",
+    "canceled",
+}
+
+_UPLOAD_CONTENT_TYPES_BY_SUFFIX = {
+    ".glb": "model/gltf-binary",
+    ".gltf": "model/gltf+json",
+    ".obj": "model/obj",
+    ".fbx": "application/vnd.autodesk.fbx",
+    ".stl": "model/stl",
+    ".usdz": "model/vnd.usdz+zip",
+    ".3mf": "model/3mf",
+    ".zip": "application/zip",
+}
+
+
+class AdMatrixClient:
+    def __init__(
+        self,
+        base_url: str,
+        auth: AuthProvider,
+        *,
+        http_client: httpx.Client | None = None,
+        timeout: float = 30,
+    ) -> None:
+        if not base_url:
+            raise ValueError("base_url is required")
+        if isinstance(auth, APIKeyAuth):
+            validate_api_key_transport(base_url)
+        self.base_url = base_url.rstrip("/")
+        self.auth = auth
+        self._http = http_client or httpx.Client(timeout=timeout)
+        self._owns_http = http_client is None
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> AdMatrixClient:
+        return self
+
+    def __exit__(self, *_args: object) -> None:
+        self.close()
+
+    def list_models(self) -> list[Model]:
+        data = self._request("GET", "/api/matrix/aimake/v1/models")
+        if not isinstance(data, list):
+            raise AdMatrixTransportError("model list response is not an array")
+        return [Model.from_dict(self._as_object(item, "model")) for item in data]
+
+    def get_model_schema(self, model_id: str) -> ModelSchema:
+        path_id = self._model_path(model_id)
+        data = self._request("GET", f"/api/matrix/aimake/v1/models/{path_id}/schema")
+        return ModelSchema.from_dict(self._as_object(data, "model schema"))
+
+    def create_upload(self, path: Path | str) -> UploadedAsset:
+        source = Path(path)
+        size = source.stat().st_size
+        content_type = _UPLOAD_CONTENT_TYPES_BY_SUFFIX.get(source.suffix.lower())
+        if content_type is None:
+            content_type = mimetypes.guess_type(source.name)[0] or "application/octet-stream"
+        session_data = self._request(
+            "POST",
+            "/api/matrix/aimake/v1/uploads",
+            json={
+                "file_name": source.name,
+                "content_type": content_type,
+                "size_bytes": size,
+            },
+        )
+        session = self._as_object(session_data, "upload session")
+        method = str(session.get("method", "PUT")).upper()
+        upload_url = str(session.get("upload_url", ""))
+        signed_headers = {
+            str(key): str(value) for key, value in dict(session.get("headers") or {}).items()
+        }
+        if method != "PUT" or not upload_url:
+            raise AdMatrixTransportError("upload session is missing a valid PUT URL")
+
+        try:
+            with source.open("rb") as content:
+                response = self._http.request(
+                    method,
+                    upload_url,
+                    headers=signed_headers,
+                    content=content,
+                )
+        except (OSError, httpx.HTTPError) as error:
+            raise AdMatrixTransportError(f"signed upload failed: {error}") from error
+        if response.status_code < 200 or response.status_code >= 300:
+            raise self._api_error(response, fallback="signed upload failed")
+        return UploadedAsset.from_dict(session)
+
+    def preview_score(
+        self,
+        model_id: str,
+        input: JsonObject,
+        request_num: int = 1,
+        *,
+        validate: bool = True,
+    ) -> Score:
+        if validate:
+            self._validate_model_input(model_id, input)
+        path_id = self._model_path(model_id)
+        data = self._request(
+            "POST",
+            f"/api/matrix/aimake/v1/models/{path_id}/score",
+            json={"input": input, "request_num": request_num},
+        )
+        score = Score.from_dict(self._as_object(data, "score"))
+        if score.score < 0 or score.total_score < 0:
+            raise AdMatrixValidationError(
+                model_id,
+                "server returned invalid negative score values",
+            )
+        return score
+
+    def generate(
+        self,
+        model_id: str,
+        input: JsonObject,
+        request_num: int = 1,
+        *,
+        idempotency_key: str | None = None,
+        ga_info: JsonObject | None = None,
+        validate: bool = True,
+    ) -> Generation:
+        if validate:
+            self._validate_model_input(model_id, input)
+
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        path_id = self._model_path(model_id)
+        request: JsonObject = {"input": input, "request_num": request_num}
+        if ga_info:
+            request["ga_info"] = ga_info
+        data = self._request_generation(
+            f"/api/matrix/aimake/v1/models/{path_id}/generate",
+            request,
+            headers,
+            retry_safe=bool(idempotency_key),
+        )
+        return Generation.from_dict(self._as_object(data, "generation"))
+
+    def _validate_model_input(self, model_id: str, input: JsonObject) -> None:
+        schema = self.get_model_schema(model_id)
+        try:
+            validator_class = jsonschema.validators.validator_for(schema.input)
+            validator_class.check_schema(schema.input)
+            validator_class(schema.input).validate(input)
+        except jsonschema.ValidationError as error:
+            path = ".".join(str(part) for part in error.absolute_path)
+            location = f" at {path}" if path else ""
+            raise AdMatrixValidationError(model_id, f"{error.message}{location}") from None
+        except jsonschema.SchemaError as error:
+            detail = f"server returned invalid schema: {error.message}"
+            raise AdMatrixValidationError(model_id, detail) from None
+
+    def get_generation(self, generation_id: str) -> Generation:
+        path_id = quote(generation_id, safe="-._~")
+        data = self._request("GET", f"/api/matrix/aimake/v1/generations/{path_id}")
+        return Generation.from_dict(self._as_object(data, "generation"))
+
+    def wait_generation(
+        self,
+        generation_id: str,
+        *,
+        poll_interval: float = 2,
+        timeout: float = 1800,
+    ) -> Generation:
+        deadline = time.monotonic() + timeout
+        while True:
+            generation = self.get_generation(generation_id)
+            if generation.status.lower() in _TERMINAL_GENERATION_STATUSES:
+                return generation
+            if time.monotonic() >= deadline:
+                raise AdMatrixTimeoutError(generation_id, timeout)
+            if poll_interval > 0:
+                time.sleep(min(poll_interval, max(0, deadline - time.monotonic())))
+
+    def download(self, url: str, destination: Path | str) -> Path:
+        target = Path(destination).expanduser().resolve()
+        target.parent.mkdir(parents=True, exist_ok=True)
+        created = False
+        try:
+            with self._http.stream("GET", url) as response:
+                if response.status_code < 200 or response.status_code >= 300:
+                    response.read()
+                    raise self._api_error(response, fallback="result download failed")
+                with target.open("xb") as output:
+                    created = True
+                    for chunk in response.iter_bytes():
+                        output.write(chunk)
+        except AdMatrixAPIError:
+            raise
+        except (OSError, httpx.HTTPError) as error:
+            if created:
+                target.unlink(missing_ok=True)
+            raise AdMatrixTransportError(f"result download failed: {error}") from error
+        return target
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        headers: dict[str, str] | None = None,
+        json: JsonObject | None = None,
+    ) -> Any:
+        request_headers = dict(self.auth.headers())
+        if headers:
+            request_headers.update(headers)
+        try:
+            response = self._http.request(
+                method,
+                f"{self.base_url}{path}",
+                headers=request_headers,
+                json=json,
+            )
+        except httpx.HTTPError as error:
+            raise AdMatrixTransportError(f"request failed: {error}") from error
+
+        try:
+            payload = response.json()
+        except ValueError:
+            if response.status_code < 200 or response.status_code >= 300:
+                raise self._api_error(response, fallback="non-JSON error response") from None
+            raise AdMatrixTransportError("ad-matrix returned a non-JSON response") from None
+
+        if not isinstance(payload, dict):
+            raise AdMatrixTransportError("ad-matrix response envelope is not an object")
+        code = payload.get("code")
+        if response.status_code < 200 or response.status_code >= 300 or code != 0:
+            raise self._api_error(response, payload=payload)
+        return payload.get("data")
+
+    def _request_generation(
+        self,
+        path: str,
+        request: JsonObject,
+        headers: dict[str, str] | None,
+        *,
+        retry_safe: bool,
+    ) -> Any:
+        attempts = 2 if retry_safe else 1
+        for attempt in range(attempts):
+            try:
+                return self._request("POST", path, headers=headers, json=request)
+            except AdMatrixTransportError:
+                if attempt + 1 >= attempts:
+                    raise
+            except AdMatrixAPIError as error:
+                if attempt + 1 >= attempts or error.status_code not in {502, 503, 504}:
+                    raise
+        raise AssertionError("unreachable generation retry state")
+
+    @staticmethod
+    def _as_object(value: Any, label: str) -> JsonObject:
+        if not isinstance(value, dict):
+            raise AdMatrixTransportError(f"{label} response is not an object")
+        return value
+
+    @staticmethod
+    def _model_path(model_id: str) -> str:
+        segments = model_id.split("/")
+        if not model_id or any(segment in {"", ".", ".."} for segment in segments):
+            raise ValueError("model_id is invalid")
+        return quote(model_id, safe="/-._~")
+
+    @staticmethod
+    def _api_error(
+        response: httpx.Response,
+        *,
+        payload: JsonObject | None = None,
+        fallback: str = "request failed",
+    ) -> AdMatrixAPIError:
+        if payload is None:
+            try:
+                decoded = response.json()
+                payload = decoded if isinstance(decoded, dict) else {}
+            except ValueError:
+                payload = {}
+        detail = payload.get("detail") or payload.get("msg") or payload.get("error") or fallback
+        return AdMatrixAPIError(
+            status_code=response.status_code,
+            code=payload.get("code"),
+            detail=str(detail),
+            request_id=response.headers.get("X-Request-Id"),
+            data=payload.get("data"),
+            retry_after=response.headers.get("Retry-After"),
+        )

admatrix_client/errors.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class AdMatrixError(Exception):
+    """Base error for safe, user-facing client failures."""
+
+
+class AdMatrixTransportError(AdMatrixError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+
+class AdMatrixAPIError(AdMatrixError):
+    def __init__(
+        self,
+        *,
+        status_code: int,
+        code: int | str | None,
+        detail: str,
+        request_id: str | None = None,
+        data: Any = None,
+        retry_after: str | None = None,
+    ) -> None:
+        self.status_code = status_code
+        self.code = code
+        self.detail = detail
+        self.request_id = request_id
+        self.data = data
+        self.limit_type = (
+            str(data.get("limit_type"))
+            if isinstance(data, dict) and data.get("limit_type")
+            else None
+        )
+        retry_value = data.get("retry_after_seconds") if isinstance(data, dict) else None
+        if retry_value is None:
+            retry_value = retry_after
+        try:
+            self.retry_after_seconds = int(retry_value) if retry_value is not None else None
+        except (TypeError, ValueError):
+            self.retry_after_seconds = None
+        request_suffix = f" (request_id={request_id})" if request_id else ""
+        super().__init__(f"ad-matrix API error {status_code}/{code}: {detail}{request_suffix}")
+
+
+class AdMatrixValidationError(AdMatrixError):
+    def __init__(self, model_id: str, detail: str) -> None:
+        self.model_id = model_id
+        self.detail = detail
+        super().__init__(f"input does not match schema for {model_id}: {detail}")
+
+
+class AdMatrixTimeoutError(AdMatrixError):
+    def __init__(self, generation_id: str, timeout: float) -> None:
+        self.generation_id = generation_id
+        self.timeout = timeout
+        super().__init__(f"generation {generation_id} did not finish within {timeout:g}s")

admatrix_client/types.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+JsonObject = dict[str, Any]
+
+
+@dataclass(frozen=True)
+class Model:
+    id: str
+    display_name: str
+    description: str
+    series_slug: str
+    series_display: str
+    material_type_slug: str
+    schema_version: str
+    selection_profile: JsonObject
+    _data: JsonObject = field(repr=False)
+
+    @classmethod
+    def from_dict(cls, data: JsonObject) -> Model:
+        return cls(
+            id=str(data.get("id", "")),
+            display_name=str(data.get("display_name", "")),
+            description=str(data.get("description", "")),
+            series_slug=str(data.get("series_slug", "")),
+            series_display=str(data.get("series_display", "")),
+            material_type_slug=str(data.get("material_type_slug", "")),
+            schema_version=str(data.get("schema_version", "")),
+            selection_profile=dict(data.get("selection_profile") or {}),
+            _data=dict(data),
+        )
+
+    def to_dict(self) -> JsonObject:
+        return dict(self._data)
+
+
+@dataclass(frozen=True)
+class ModelSchema:
+    input: JsonObject
+    output: JsonObject
+    schema_version: str
+    selection_profile: JsonObject
+    _data: JsonObject = field(repr=False)
+
+    @classmethod
+    def from_dict(cls, data: JsonObject) -> ModelSchema:
+        return cls(
+            input=dict(data.get("input") or {}),
+            output=dict(data.get("output") or {}),
+            schema_version=str(data.get("schema_version", "")),
+            selection_profile=dict(data.get("selection_profile") or {}),
+            _data=dict(data),
+        )
+
+    def to_dict(self) -> JsonObject:
+        return dict(self._data)
+
+
+@dataclass(frozen=True)
+class Score:
+    score: int
+    total_score: int
+    request_num: int
+    _data: JsonObject = field(repr=False)
+
+    @classmethod
+    def from_dict(cls, data: JsonObject) -> Score:
+        return cls(
+            score=int(data.get("score", 0)),
+            total_score=int(data.get("total_score", 0)),
+            request_num=int(data.get("request_num", 1)),
+            _data=dict(data),
+        )
+
+    def to_dict(self) -> JsonObject:
+        return dict(self._data)
+
+
+@dataclass(frozen=True)
+class Generation:
+    id: str
+    model_id: str
+    status: str
+    request_num: int
+    score: int | None
+    outputs: list[JsonObject]
+    _data: JsonObject = field(repr=False)
+
+    @classmethod
+    def from_dict(cls, data: JsonObject) -> Generation:
+        return cls(
+            id=str(data.get("id") or data.get("gen_id") or ""),
+            model_id=str(data.get("model_id", "")),
+            status=str(data.get("status", "")),
+            request_num=int(data.get("request_num", 1)),
+            score=int(data["score"]) if data.get("score") is not None else None,
+            outputs=[dict(item) for item in data.get("outputs") or []],
+            _data=dict(data),
+        )
+
+    def to_dict(self) -> JsonObject:
+        return dict(self._data)
+
+
+@dataclass(frozen=True)
+class UploadedAsset:
+    public_url: str
+    object_key: str
+    expires_at: str
+    delete_after: str
+    _data: JsonObject = field(repr=False)
+
+    @classmethod
+    def from_dict(cls, data: JsonObject) -> UploadedAsset:
+        return cls(
+            public_url=str(data.get("public_url", "")),
+            object_key=str(data.get("object_key", "")),
+            expires_at=str(data.get("expires_at", "")),
+            delete_after=str(data.get("delete_after", "")),
+            _data=dict(data),
+        )
+
+    def to_dict(self) -> JsonObject:
+        return {
+            "public_url": self.public_url,
+            "object_key": self.object_key,
+            "expires_at": self.expires_at,
+            "delete_after": self.delete_after,
+        }

admatrix_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: admatrix-client
+Version: 0.1.0
+Summary: Generic Python client and yc CLI for the ad-matrix model API
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: jsonschema<5,>=4.23
+Requires-Dist: keyring<26,>=25
+Description-Content-Type: text/markdown
+
+# ad-matrix Python client and `yc` CLI
+
+This package is the generic client for the model catalog exposed by ad-matrix.
+It contains no model IDs or Provider-specific behavior: models, JSON Schemas,
+selection metadata, and generation results are discovered at runtime.
+
+## Installation
+
+Install the CLI as an isolated tool:
+
+```bash
+uv tool install admatrix-client
+# or: pipx install admatrix-client
+```
+
+For one-off use without a persistent installation:
+
+```bash
+uvx --from admatrix-client yc --help
+```
+
+Python integrations can install the same package with their normal package
+manager and import `admatrix_client`.
+
+The command-line client is installed as `yc`. Set the service URL explicitly:
+
+```bash
+export YC_BASE_URL=https://your-ad-matrix-host
+yc auth login
+yc models list
+yc generate --model MODEL_ID --input @payload.json --wait
+```
+
+`yc` requires HTTPS so API Keys are never sent over plaintext transport.
+Plain HTTP is accepted only for `localhost` and loopback addresses during
+local development.
+
+`--json` can appear before or after a command. It always writes one JSON
+document to stdout, including for validation, authentication, rate-limit, and
+service errors.
+
+For automation, `YC_API_KEY` takes precedence over the stored credential.
+matrix-agent injects its current runtime JWT through `RuntimeJWTAuth` and uses
+the same `AdMatrixClient`; it does not need an API Key.
+
+The plaintext API Key is never printed by `yc`. Login prefers the operating
+system keychain and prompts through a hidden terminal input; it never accepts
+the Key as a command-line argument. The fallback credential file must be
+owner-only (`0600`) or the client refuses to load it. When a fallback file
+exists, it remains authoritative until the next successful login stores the
+new Key in the system keychain and removes the file.
+
+Local input validation follows the JSON Schema draft declared by ad-matrix.
+API failures preserve request IDs and structured rate-limit metadata such as
+`limit_type` and `retry_after_seconds`.
+
+## Commands
+
+```bash
+yc auth login|logout|status
+yc models list
+yc models schema MODEL_ID
+yc upload ./reference.png
+yc score --model MODEL_ID --input @payload.json
+yc generate --model MODEL_ID --input @payload.json --request-num 2 --wait
+yc generations get GENERATION_ID
+yc generations wait GENERATION_ID
+```
+
+Any string value inside the input JSON that starts with `@` and resolves to a
+local file is uploaded first and replaced with its public URL. Relative paths
+are resolved from the payload file:
+
+```json
+{
+  "prompt": "一只猫在雨夜的霓虹街道上奔跑",
+  "references": [{ "image_url": "@reference.png" }]
+}
+```
+
+Upload sessions are accounted per 亿创 user, not per API Key, so creating
+multiple Keys does not multiply the allowance. The current defaults are 30
+signed sessions per minute and 10 GiB of signed bytes per UTC day; deployments
+may override them. A signed URL is valid for 10 minutes, and its required
+`x-obs-expires` header makes the temporary object expire after 7 days. The
+`yc upload --json` response includes `expires_at` and the latest server-side
+deletion boundary in `delete_after`.
+
+When `--wait` is used, successful managed resource files are downloaded to
+`yc-output/<generation_id>/` by default, or to the directory supplied through
+`--output`. Existing files are never overwritten. A partial generation keeps
+its successful downloads and the complete failed-output list, then exits with
+code 7. The terminal `score` is the final settled score; the score returned by
+the initial generate call is only the estimate/reservation.
+
+The CLI creates one idempotency key for each generate command. A lost response
+or retryable gateway failure is retried once with that same key, so the retry
+does not create a second task or charge.
+Keys are user-global across all model generation routes, so one key must never
+be reused for a different model or a different generation request.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 2 | Command argument, JSON, or model Schema error |
+| 3 | Missing or invalid authentication |
+| 4 | Insufficient score |
+| 5 | User/model rate or concurrency limit |
+| 6 | Network, timeout, or service failure |
+| 7 | Generation terminal failure or partial failure |
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+uv build
+```
+
+Release artifacts are published to PyPI so matrix-agent and external tools
+resolve the same immutable package source and hashes. Do not use a sibling
+filesystem dependency or copy the HTTP client into a consuming repository.

admatrix_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+admatrix_client/__init__.py,sha256=TefzGXP5U5qEZZHbcZdTYJxFs1L9FbKsw8CnmGZ2ldc,629
+admatrix_client/auth.py,sha256=qh3mS77OEkpVHgg0LAS2l7r6BWyfbbvI6gEe4lafl28,7642
+admatrix_client/client.py,sha256=qPHHMThXE_RjmN5TokYhBnzNB-tdbDXP3rSxZW4TF38,11541
+admatrix_client/errors.py,sha256=0HTdJeXpkdfSGQocRtoHB-dqcQJtf_W_c3uHIwqv7lg,1936
+admatrix_client/types.py,sha256=VgH8bEQv84K5rbz8d_oRjZhptrdH7RSsCw_kPdYEReM,3772
+yc_cli/__init__.py,sha256=KEAXzI_9PVfw0PzcboRw5tIhS-1MfsSEb5vJOfTNEx4,45
+yc_cli/main.py,sha256=ohqVOkIasfzId1yy4O4h7cZSb3b8SEueNrkBQgKJw2E,16185
+admatrix_client-0.1.0.dist-info/METADATA,sha256=oRzzNuGdLm0TFM1FOH8miu7pwWOAhS3bfb54hHmc2Bk,4861
+admatrix_client-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+admatrix_client-0.1.0.dist-info/entry_points.txt,sha256=yKlUmmLb85KAeM4vC5KfPBXuD2DmzR9LOZkKjQmvQCs,39
+admatrix_client-0.1.0.dist-info/RECORD,,

admatrix_client-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

admatrix_client-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+yc = yc_cli.main:run

yc_cli/__init__.py

@@ -0,0 +1 @@
+"""Command-line interface package for yc."""

yc_cli/main.py

@@ -0,0 +1,454 @@
+from __future__ import annotations
+
+import argparse
+import getpass
+import json
+import os
+import sys
+import uuid
+from pathlib import Path
+from typing import Any
+from urllib.parse import unquote, urlparse
+
+from admatrix_client import (
+    AdMatrixAPIError,
+    AdMatrixClient,
+    AdMatrixError,
+    AdMatrixTimeoutError,
+    AdMatrixTransportError,
+    AdMatrixValidationError,
+    APIKeyAuth,
+)
+from admatrix_client.auth import CredentialStore, resolve_api_key, validate_api_key_transport
+
+
+class CLIError(Exception):
+    def __init__(self, message: str, exit_code: int = 2) -> None:
+        self.exit_code = exit_code
+        super().__init__(message)
+
+
+EXIT_SUCCESS = 0
+EXIT_USAGE = 2
+EXIT_AUTH = 3
+EXIT_SCORE = 4
+EXIT_RATE_LIMIT = 5
+EXIT_SERVICE = 6
+EXIT_GENERATION_FAILED = 7
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="yc", description="亿创模型命令行客户端")
+    _add_common_options(parser)
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    auth = commands.add_parser("auth", help="管理 API Key")
+    _add_common_options(auth, suppress_defaults=True)
+    auth_commands = auth.add_subparsers(dest="auth_command", required=True)
+    auth_login = auth_commands.add_parser("login", help="安全提示并保存 API Key")
+    _add_common_options(auth_login, suppress_defaults=True)
+    auth_logout = auth_commands.add_parser("logout", help="删除本地 API Key")
+    _add_common_options(auth_logout, suppress_defaults=True)
+    auth_status = auth_commands.add_parser("status", help="查看鉴权状态")
+    _add_common_options(auth_status, suppress_defaults=True)
+
+    models = commands.add_parser("models", help="查看服务端模型目录")
+    _add_common_options(models, suppress_defaults=True)
+    model_commands = models.add_subparsers(dest="models_command", required=True)
+    models_list = model_commands.add_parser("list")
+    _add_common_options(models_list, suppress_defaults=True)
+    schema = model_commands.add_parser("schema")
+    _add_common_options(schema, suppress_defaults=True)
+    schema.add_argument("model_id")
+
+    upload = commands.add_parser("upload", help="上传本地素材")
+    _add_common_options(upload, suppress_defaults=True)
+    upload.add_argument("path", type=Path)
+
+    score = commands.add_parser("score", help="预估积分")
+    _add_common_options(score, suppress_defaults=True)
+    _add_generation_input(score)
+
+    generate = commands.add_parser("generate", help="提交生成任务")
+    _add_common_options(generate, suppress_defaults=True)
+    _add_generation_input(generate)
+    generate.add_argument("--idempotency-key")
+    generate.add_argument("--wait", action="store_true")
+    generate.add_argument("--output", type=Path)
+    generate.add_argument("--timeout", type=float, default=1800)
+    generate.add_argument("--poll-interval", type=float, default=2)
+
+    generations = commands.add_parser("generations", help="查看生成任务")
+    _add_common_options(generations, suppress_defaults=True)
+    generation_commands = generations.add_subparsers(dest="generations_command", required=True)
+    get_command = generation_commands.add_parser("get")
+    _add_common_options(get_command, suppress_defaults=True)
+    get_command.add_argument("generation_id")
+    wait_command = generation_commands.add_parser("wait")
+    _add_common_options(wait_command, suppress_defaults=True)
+    wait_command.add_argument("generation_id")
+    wait_command.add_argument("--output", type=Path)
+    wait_command.add_argument("--timeout", type=float, default=1800)
+    wait_command.add_argument("--poll-interval", type=float, default=2)
+    return parser
+
+
+def _add_common_options(
+    parser: argparse.ArgumentParser,
+    *,
+    suppress_defaults: bool = False,
+) -> None:
+    default_base_url: Any = argparse.SUPPRESS if suppress_defaults else os.getenv("YC_BASE_URL")
+    default_json: Any = argparse.SUPPRESS if suppress_defaults else False
+    parser.add_argument("--base-url", default=default_base_url)
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        dest="json_output",
+        default=default_json,
+    )
+
+
+def _add_generation_input(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--model", required=True)
+    parser.add_argument("--input", required=True, dest="input_value")
+    parser.add_argument("--request-num", type=int, default=1)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    raw_args = list(sys.argv[1:] if argv is None else argv)
+    try:
+        args = parser.parse_args(raw_args)
+    except SystemExit as error:
+        if error.code and "--json" in raw_args:
+            _emit(
+                {
+                    "error": {
+                        "type": "ArgumentError",
+                        "message": "命令参数错误",
+                        "exit_code": EXIT_USAGE,
+                    }
+                },
+                True,
+            )
+            return EXIT_USAGE
+        raise
+    try:
+        if args.command == "auth":
+            return _handle_auth(args)
+
+        client = _build_client(args)
+        try:
+            result = _dispatch(client, args)
+        finally:
+            client.close()
+        _emit(result, args.json_output)
+        return _result_exit_code(args, result)
+    except (CLIError, AdMatrixError, OSError, ValueError, json.JSONDecodeError) as error:
+        exit_code = _error_exit_code(error)
+        if args.json_output:
+            _emit(_error_payload(error, exit_code), True)
+        else:
+            print(str(error), file=sys.stderr)
+        return exit_code
+
+
+def run() -> None:
+    raise SystemExit(main())
+
+
+def _build_client(args: argparse.Namespace) -> AdMatrixClient:
+    if not args.base_url:
+        raise CLIError("未配置服务地址，请设置 YC_BASE_URL 或传 --base-url", EXIT_USAGE)
+    _validate_cli_base_url(args.base_url)
+    api_key, _source = resolve_api_key()
+    if not api_key:
+        raise CLIError("未配置 API Key，请先运行 yc auth login 或设置 YC_API_KEY", EXIT_AUTH)
+    return AdMatrixClient(args.base_url, APIKeyAuth(api_key))
+
+
+def _validate_cli_base_url(base_url: str) -> None:
+    try:
+        validate_api_key_transport(base_url)
+    except ValueError as error:
+        raise CLIError(
+            "服务地址必须使用 HTTPS；仅 localhost 和回环地址允许 HTTP",
+            EXIT_USAGE,
+        ) from error
+
+
+def _handle_auth(args: argparse.Namespace) -> int:
+    store = CredentialStore()
+    if args.auth_command == "login":
+        api_key = getpass.getpass("API Key: ")
+        try:
+            source = store.save(api_key)
+        except OSError as error:
+            raise CLIError(str(error), EXIT_AUTH) from error
+        _emit({"configured": True, "source": source}, args.json_output)
+        return 0
+    if args.auth_command == "logout":
+        try:
+            store.delete()
+        except OSError as error:
+            raise CLIError(str(error), EXIT_AUTH) from error
+        api_key, source = resolve_api_key(store)
+        _emit(
+            {"configured": bool(api_key), "source": source},
+            args.json_output,
+        )
+        return EXIT_AUTH if api_key else EXIT_SUCCESS
+    api_key, source = resolve_api_key(store)
+    _emit({"configured": bool(api_key), "source": source}, args.json_output)
+    return EXIT_SUCCESS if api_key else EXIT_AUTH
+
+
+def _dispatch(client: AdMatrixClient, args: argparse.Namespace) -> Any:
+    if args.command == "models":
+        if args.models_command == "list":
+            return [model.to_dict() for model in client.list_models()]
+        return client.get_model_schema(args.model_id).to_dict()
+    if args.command == "upload":
+        return client.create_upload(args.path).to_dict()
+    if args.command == "score":
+        payload = _load_and_upload_input(client, args.input_value)
+        return client.preview_score(args.model, payload, args.request_num).to_dict()
+    if args.command == "generate":
+        if args.output is not None and not args.wait:
+            raise CLIError("--output 只能与 --wait 一起使用")
+        payload = _load_and_upload_input(client, args.input_value)
+        idempotency_key = args.idempotency_key or str(uuid.uuid4())
+        generation = client.generate(
+            args.model,
+            payload,
+            args.request_num,
+            idempotency_key=idempotency_key,
+        )
+        if args.wait:
+            generation = client.wait_generation(
+                generation.id,
+                timeout=args.timeout,
+                poll_interval=args.poll_interval,
+            )
+            return _download_generation_outputs(client, generation, args.output)
+        return generation.to_dict()
+    if args.command == "generations":
+        if args.generations_command == "get":
+            return client.get_generation(args.generation_id).to_dict()
+        generation = client.wait_generation(
+            args.generation_id,
+            timeout=args.timeout,
+            poll_interval=args.poll_interval,
+        )
+        return _download_generation_outputs(client, generation, args.output)
+    raise CLIError("未知命令")
+
+
+def _load_input(value: str) -> dict[str, Any]:
+    if value == "-":
+        raw = sys.stdin.read()
+    elif value.startswith("@"):
+        raw = Path(value[1:]).read_text(encoding="utf-8")
+    else:
+        raw = value
+    payload = json.loads(raw)
+    if not isinstance(payload, dict):
+        raise CLIError("--input 必须是 JSON 对象")
+    return payload
+
+
+def _load_and_upload_input(client: AdMatrixClient, value: str) -> dict[str, Any]:
+    payload = _load_input(value)
+    base_dir = (
+        Path(value[1:]).expanduser().resolve().parent if value.startswith("@") else Path.cwd()
+    )
+    resolved = _upload_local_references(client, payload, base_dir)
+    if not isinstance(resolved, dict):
+        raise CLIError("--input 必须是 JSON 对象")
+    return resolved
+
+
+def _upload_local_references(client: AdMatrixClient, value: Any, base_dir: Path) -> Any:
+    if isinstance(value, dict):
+        return {
+            key: _upload_local_references(client, item, base_dir) for key, item in value.items()
+        }
+    if isinstance(value, list):
+        return [_upload_local_references(client, item, base_dir) for item in value]
+    if not isinstance(value, str) or not value.startswith("@") or len(value) == 1:
+        return value
+
+    path = Path(value[1:]).expanduser()
+    if not path.is_absolute():
+        path = base_dir / path
+    if not path.is_file():
+        return value
+    return client.create_upload(path).public_url
+
+
+def _download_generation_outputs(
+    client: AdMatrixClient,
+    generation: Any,
+    output: Path | None,
+) -> dict[str, Any]:
+    result = generation.to_dict()
+    output_dir = (
+        output.expanduser().resolve()
+        if output is not None
+        else (Path.cwd() / "yc-output" / generation.id).resolve()
+    )
+    downloads: list[dict[str, Any]] = []
+    seen_urls: set[str] = set()
+
+    for item in generation.outputs:
+        if item.get("item_status") != "succeeded":
+            continue
+        output_index = int(item.get("index", 0))
+        for remote_url in _collect_output_urls(item):
+            if remote_url in seen_urls:
+                continue
+            seen_urls.add(remote_url)
+            output_dir.mkdir(parents=True, exist_ok=True)
+            destination = _unique_download_path(output_dir, remote_url, output_index)
+            local_path = client.download(remote_url, destination)
+            downloads.append(
+                {
+                    "output_index": output_index,
+                    "remote_url": remote_url,
+                    "local_path": str(local_path.resolve()),
+                }
+            )
+
+    result["downloads"] = downloads
+    return result
+
+
+def _collect_output_urls(item: dict[str, Any]) -> list[str]:
+    resources = item.get("resources")
+    resource_urls: list[str] = []
+    if isinstance(resources, list):
+        for resource in resources:
+            if not isinstance(resource, dict):
+                continue
+            resource_urls.extend(_collect_http_urls(resource.get("url")))
+    return resource_urls
+
+
+def _collect_http_urls(value: Any) -> list[str]:
+    if isinstance(value, dict):
+        urls: list[str] = []
+        for item in value.values():
+            urls.extend(_collect_http_urls(item))
+        return urls
+    if isinstance(value, list):
+        urls = []
+        for item in value:
+            urls.extend(_collect_http_urls(item))
+        return urls
+    if isinstance(value, str):
+        parsed = urlparse(value)
+        if parsed.scheme in {"http", "https"} and parsed.netloc:
+            return [value]
+    return []
+
+
+def _unique_download_path(output_dir: Path, remote_url: str, output_index: int) -> Path:
+    raw_name = unquote(Path(urlparse(remote_url).path).name)
+    name = Path(raw_name).name if raw_name else f"output-{output_index}"
+    candidate = output_dir / name
+    if not candidate.exists():
+        return candidate
+
+    suffix = candidate.suffix
+    stem = candidate.stem or f"output-{output_index}"
+    candidate = output_dir / f"{stem}-{output_index}{suffix}"
+    counter = 2
+    while candidate.exists():
+        candidate = output_dir / f"{stem}-{output_index}-{counter}{suffix}"
+        counter += 1
+    return candidate
+
+
+def _emit(value: Any, json_output: bool) -> None:
+    if json_output:
+        print(json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":")))
+        return
+    if isinstance(value, dict) and set(value) <= {"configured", "source"}:
+        if value.get("configured"):
+            print(f"已配置（来源：{value.get('source')}）")
+        else:
+            print("未配置")
+        return
+    print(json.dumps(value, ensure_ascii=False, indent=2, sort_keys=True))
+
+
+def _result_exit_code(args: argparse.Namespace, value: Any) -> int:
+    is_generation_result = args.command == "generations" or (
+        args.command == "generate" and bool(args.wait)
+    )
+    if not is_generation_result or not isinstance(value, dict):
+        return EXIT_SUCCESS
+
+    status = str(value.get("status", "")).lower()
+    if status in {"partial", "failed", "error", "cancelled", "canceled"}:
+        return EXIT_GENERATION_FAILED
+    if status != "completed":
+        return EXIT_SUCCESS
+
+    outputs = value.get("outputs")
+    if not isinstance(outputs, list) or not outputs:
+        return EXIT_GENERATION_FAILED
+    if any(
+        not isinstance(output, dict) or output.get("item_status") != "succeeded"
+        for output in outputs
+    ):
+        return EXIT_GENERATION_FAILED
+    return EXIT_SUCCESS
+
+
+def _error_exit_code(error: Exception) -> int:
+    if isinstance(error, CLIError):
+        return error.exit_code
+    if isinstance(error, AdMatrixValidationError):
+        return EXIT_USAGE
+    if isinstance(error, AdMatrixAPIError):
+        if error.status_code in {401, 403}:
+            return EXIT_AUTH
+        if error.status_code == 402:
+            return EXIT_SCORE
+        if error.status_code == 429:
+            return EXIT_RATE_LIMIT
+        if error.status_code >= 500:
+            return EXIT_SERVICE
+        return EXIT_USAGE
+    if isinstance(error, (AdMatrixTimeoutError, AdMatrixTransportError)):
+        return EXIT_SERVICE
+    if isinstance(error, AdMatrixError):
+        return EXIT_SERVICE
+    return EXIT_USAGE
+
+
+def _error_payload(error: Exception, exit_code: int) -> dict[str, Any]:
+    detail: dict[str, Any] = {
+        "type": type(error).__name__,
+        "message": str(error),
+        "exit_code": exit_code,
+    }
+    if isinstance(error, AdMatrixAPIError):
+        detail.update(
+            {
+                "status_code": error.status_code,
+                "code": error.code,
+                "request_id": error.request_id,
+                "limit_type": error.limit_type,
+                "retry_after_seconds": error.retry_after_seconds,
+            }
+        )
+    elif isinstance(error, AdMatrixValidationError):
+        detail["model_id"] = error.model_id
+    return {"error": detail}
+
+
+if __name__ == "__main__":
+    run()