admatrix-client 0.1.0__tar.gz

admatrix_client-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/

admatrix_client-0.1.0/PKG-INFO

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

@@ -0,0 +1,125 @@
+# 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/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "admatrix-client"
+version = "0.1.0"
+description = "Generic Python client and yc CLI for the ad-matrix model API"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+  "httpx>=0.27,<1",
+  "jsonschema>=4.23,<5",
+  "keyring>=25,<26",
+]
+
+[project.scripts]
+yc = "yc_cli.main:run"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/admatrix_client", "src/yc_cli"]
+
+[dependency-groups]
+dev = [
+  "pytest>=9.0.3,<10",
+  "ruff>=0.12,<1",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]

admatrix_client-0.1.0/src/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-0.1.0/src/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