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:

uv tool install admatrix-client
# or: pipx install admatrix-client

For one-off use without a persistent installation:

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:

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

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:

{
  "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

Development

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.