Metadata-Version: 2.4
Name: instance-repo
Version: 0.7.0
Summary: InstanceRepo SDK — 评测 Instance 统一存储客户端（SDK-only；控制面由 apiserver 承载）
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: tomli>=1.1.0; python_version < "3.11"
Provides-Extra: oss
Requires-Dist: oss2>=2.19; extra == "oss"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: coverage>=7; extra == "dev"

# instance-repo

InstanceRepo Python SDK 与 `irepo` 命令行工具——评测 Instance 的统一存储客户端。

SDK 只负责客户端逻辑；控制面（元数据、鉴权、STS 凭据签发）由 apiserver 承载，数据面
（OSS 读写、镜像推拉）经 apiserver 下发的临时凭据直连。SDK **不内置**任何 apiserver
域名、环境名、OSS bucket / endpoint / region、ACR registry / namespace 等基础设施信息，
这些值一律在运行时由调用方通过环境变量或构造参数注入（见下文“配置”）。

Python SDK 与 Go SDK 功能、错误码、行为逐字对齐。

## 安装

```bash
pip install instance-repo            # SDK + irepo CLI（Python ≥ 3.10）
pip install "instance-repo[oss]"     # 需要数据面 OSS 读写时，附带 oss2
```

镜像推拉依赖外部二进制 `skopeo`；未安装时相关操作会被跳过（`push_image=False` / `--no-image`）。

## 配置

所有基础设施地址在运行时注入，优先级：构造参数 > 环境变量 > 空（用到时才校验并报错）。

控制面：

- `INSTANCEREPO_API_BASE`：apiserver 根地址（必填，无内置默认）
- `IR_API_ENV`：下发的 `Env` 请求头值，apiserver 据此路由（原样下发，无别名映射）
- `INSTANCEREPO_TOKEN`：身份 token（`X-API-Key`）
- `IR_NETWORK`：数据面走 `internal`（默认）还是 `public`（VPC 外须设 `public`）

数据面（按需，仅在真正读写 OSS / 镜像时才需要）：

- `IR_OSS_BUCKET`、`IR_ACR_HOST`、`IR_ACR_NAMESPACE`
- `IR_OSS_PREFIX`：bucket 内对象目录前缀，协议常量，默认 `swe/datasets`
- `IR_SCAFFOLD_BUCKET`、`IR_SCAFFOLD_ROOT`：scaffold 包存储位置

`profile` 名仅作标签，不再对应任何内置取值；也可用 `profile_overrides={...}` 传入等价字段。

## 快速开始

```python
from instance_repo import Repo

repo = Repo()  # 从环境变量读取 api_base / token / 数据面配置

# 控制面元数据操作（不需要数据面配置）
datasets = repo.datasets.list()
versions = repo.versions.list("alibaba/mybench")
state = repo.versions.status("alibaba/mybench", "v1")

# 身份自查：返回当前 token 对应工号，用于拼 user-data 前缀 swe/user-data/users/{uid}/
uid = repo.whoami()

# 用户输入数据（插件 / 数据合成输入）
repo.upload_user_data(uid, "plugin.bin", "plugins/plugin.bin")
keys = repo.list_user_data(uid)
```

未配置 `INSTANCEREPO_API_BASE` 时，发起控制面请求会抛出明确的 `SchemaError` 引导设置该变量；
数据面操作在真正用到某字段（如 `oss_bucket`）时才校验，纯控制面操作不受影响。

## CLI

```bash
irepo --help
# 子命令：validate / push / pull / list / get / publish / grant / feedback
#         report / whoami / user-data / create / claim / version
```

跨环境上架的目标数据面地址通过参数显式提供（SDK 不内置任何桶/仓地址）：

```bash
irepo publish alibaba/mybench/v1 \
  --target-bucket <your-oss-bucket> \
  --target-acr <your-registry-host> --target-acr-namespace <your-namespace>
```

## 版本与文档

版本号在 `pyproject.toml` / `instance_repo.__version__` / Go `version.go` /
conformance golden 四处保持一致。各环境的真实配置取值、端到端示例与错误码对照，见团队内部
部署文档。
