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.