Metadata-Version: 2.4
Name: admatrix-client
Version: 0.1.1
Summary: Thin yc CLI for the existing ad-matrix generation API
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 亿创 Generation CLI

`yc` 是现有 ad-matrix generation API 的轻量命令行封装。它不保存模型列表，
也不理解任何模型的专属参数；模型 ID 和完整请求 JSON 会直接发送给服务端。

因此，只要新模型继续使用现有 generation API，CLI 就不需要更新或重新发布。

## 安装

从仓库安装：

```bash
pip install ./clients/python
```

发布到 Python 包仓库后可使用：

```bash
pip install admatrix-client
```

安装后会提供 `yc` 命令。

## 配置环境

CLI 不保存 API Key。调用前设置服务地址和个人 API Key：

```bash
export YC_BASE_URL="https://example.test"
export YC_API_KEY="your-api-key"
```

测试环境和正式环境使用同一个安装包，只需切换 `YC_BASE_URL`。也可以用一次性的
`--base-url` 覆盖环境变量：

```bash
yc --base-url "https://another.example" models
```

API Key 只能通过 `YC_API_KEY` 提供，不支持命令行参数，避免它进入命令历史和进程列表。

## 查看当前模型

```bash
yc models
```

模型来自服务端当前 registry，CLI 中没有模型 ID 白名单。

## 提交并等待结果

`--data` 是现有 `GenerateRequest` 的完整 JSON：

```bash
yc generate seedance-2-0 \
  --data '{"input":{"prompt":"一只在月球散步的猫"},"request_num":1}' \
  --wait
```

CLI 只提交一次 generation 请求。拿到 `gen_id` 后，`--wait` 默认每 2 秒查询一次
status；任务进入 `completed` 后，输出包含 `outputs`、结果 URL 或失败原因的完整 JSON。

默认最长等待 1800 秒，可调整：

```bash
yc generate seedance-2-0 \
  --data @request.json \
  --wait \
  --poll-interval 3 \
  --wait-timeout 3600
```

轮询间隔和最长等待都必须是有限且大于 `0` 的秒数。
超时只会停止本地轮询，不会取消服务端任务。

## JSON 输入方式

内联 JSON：

```bash
yc generate MODEL_ID --data '{"input":{"prompt":"hello"}}'
```

从文件读取：

```bash
yc generate MODEL_ID --data @request.json
```

从标准输入读取，适合 Codex 或脚本：

```bash
printf '%s' '{"input":{"prompt":"hello"}}' | yc generate MODEL_ID --data - --wait
```

CLI 会透传整个 JSON 对象，所以 `provider_id`、`dry_run`、`ga_info`、
`callback_url` 等现有通用字段不需要额外 CLI 参数。

## 查询已有任务

只查询一次：

```bash
yc status MODEL_ID GENERATION_ID
```

持续轮询最终结果：

```bash
yc wait MODEL_ID GENERATION_ID --poll-interval 2 --wait-timeout 1800
```

## 输出与退出状态

- 成功响应以 JSON 输出到 stdout，保持服务端的 `code/detail/data` 结构。
- 配置、输入、网络、API 或超时错误以 JSON 输出到 stderr。
- 成功退出码为 `0`，运行时/API 错误为 `1`，配置或输入错误为 `2`。
- 服务端即使返回 HTTP 200，只要业务 `code` 非 0，CLI 仍按失败处理。
- CLI 不跟随 HTTP 重定向，避免把 API Key 转发到其他地址；请直接配置最终服务地址。

## 本期边界

本包不提供本地文件上传、结果自动下载、模型 Schema 校验、API Key 创建或持久化。
这些能力不影响它作为 generation API 通用调用器使用。
