Metadata-Version: 2.5
Name: ikc-video-sdk
Version: 0.1.0
Summary: IKC 视频引擎（ikc-video-service）客户端 SDK：typed 视频资源方法 + 统一壳解包 + 身份信任头/traceId/幂等重试装配
Author: SITECH-iKM
Requires-Python: >=3.12
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: ikc-sdk-lib==0.12.1
Requires-Dist: pydantic<3.0,>=2.7
Description-Content-Type: text/markdown

# ikc-video-sdk

IKC 视频引擎（ikc-video-service）的独立客户端 SDK 分发（导入包 `ikc_video_sdk`）。

- 与 `ikc-video` 服务端 wheel 中的 `ikc_video_sdk` **同源**（`force-include` 自 `../src/ikc_video_sdk`），版本号保持一致；
- 供下游（pipeline / ikc-open-platform 等）以正常依赖模式引用，**无需安装服务端重型依赖**（celery/redis/fastapi/pyuploadx 等）；
- 能力面：typed 视频资源方法（V-01 异步切片、V-02 同步处理）+ 系统路由（`/`、`/health`、`/ready`、`/api/catalog`、`/api/error-codes`）+ 泛化 `client.request`；
  统一响应壳解包与类型化异常；身份信任头 / Bearer / 23 位 traceId / 幂等重试装配。

用法与资源清单见 `docs/客户端SDK设计与使用.md`。

## 跨层能力来自 ikc-sdk-lib（不自定义）

| 能力 | 来源 |
| --- | --- |
| traceId 生成/校验/提取（23 位纯数字） | `ikc_sdk.core.trace` |
| trace 头与身份信任头常量 | `ikc_sdk.core.headers` |
| 通用稳定错误码（`000000/100001/100401/…/999999`） | `ikc_sdk.core.codes` |
| SDK 异常基类（家族统一兜底捕获） | `ikc_sdk.core.exceptions.IkcSdkError` |

视频域 `260xxx` 与下游 `509xxx` 码字面量由本 SDK 的 `ikc_video_sdk.codes` 发布，
与服务端 registry（`/api/error-codes`）的一致性由 `tests/test_sdk_contract.py` 守护。

## 安装

```bash
pip install /home/sharkyai/ikc-video-service/sdk/dist/ikc_video_sdk-0.1.0-py3-none-any.whl
```

## 快速开始

```python
from ikc_video_sdk import IkCVideoClient

with IkCVideoClient("http://127.0.0.1:19200", token="dev-token") as client:
    print(client.system.health())                      # {"status": "ok", ...}

    # V-01 异步切片：请求体嵌套 media（与 V-02 的扁平形状不同，由 SliceRequest 固化）
    accepted = client.video.slice(
        media={"source_format": "mp4", "object_key": "mm/video/a.mp4"}, mode="scene"
    )
    print(accepted.taskId)                             # 结果由上游按 taskId 获取

    # V-02 同步处理：扁平请求体，阻塞至 mm-schema 清单产出
    result = client.video.process(object_key="mm/video/a.mp4", klgId="klg_1")
    print(result.manifest_key, len(result.segments))
```

> 入参三选一：请求模型（`SliceRequest` / `VideoProcessRequest`，SDK 侧即校验）、
> 线缆 dict（原样透传，服务端校验）、关键字字段（按模型校验后只发显式传入的字段）。
> **V-01 的媒体来源在 `media` 下**（`media.object_key` / `media.input_url` 二选一），
> V-02 则在顶层，传错形状会得到 `100001`。

异步版方法同名（`AsyncIkCVideoClient`），生产（`IKC_VIDEO_AUTH_MODE=gateway_header`）
传 `identity=CallerIdentity(user_id=..., tenant_id=...)` 以透传信任头。

## 版本与兼容性

| ikc-video-sdk | 依赖 ikc-sdk-lib | 说明 |
| --- | --- | --- |
| `0.1.0` | `==0.12.1` | 首个独立分发版本（对齐 ikc-video `0.1.0`） |

> 升级 `ikc-sdk-lib` pin 属兼容性变更，须与服务端 `pyproject.toml` 同步；
> 所有涉及 Celery 的依赖组另受 `/home/sharkyai/依赖版本强制契约.md` 约束（SDK 不引入 celery）。

> 分发形态：本包**只发布 wheel**（`sdk/dist/ikc_video_sdk-<version>-py3-none-any.whl`）。
> sdist 在「由 sdist 重建 wheel」时会因 `force-include` 的相对路径（`../src/ikc_video_sdk`）失效而失败，故不上传 sdist。
