Metadata-Version: 2.4
Name: las_sdk
Version: 0.2.0
Summary: Python SDK for Volcengine LAS (Large-scale Audio/Video Service)
License: MIT
Requires-Python: >=3.9
Requires-Dist: httpx>=0.28.1
Requires-Dist: pypdf>=3.0.0
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# LAS SDK

LAS Operator 统一 Python SDK，提供 CLI 工具 `lasutil` 和可编程接口。

## 安装

```bash
# 始终安装最新版本
pip install https://hyy-rd.tos-cn-beijing.volces.com/skills/sdk/las_sdk-0.2.0-py3-none-any.whl
```

> 依赖 `requests`, `httpx`, `pypdf`。纯 Python，兼容 Python 3.9+。

## 本地构建 wheel

```bash
cd las_sdk
uv build
```

产物路径：`dist/las_sdk-<version>-py3-none-any.whl`

## 环境变量

| 变量 | 必填 | 说明 |
|------|------|------|
| `LAS_API_KEY` | **是** | LAS 平台 API Key（也可通过当前目录 `env.sh` 提供） |
| `LAS_REGION` / `REGION` | 否 | Region，默认 `cn-beijing`，可选 `cn-shanghai` |
| `VOLCENGINE_ACCESS_KEY` | TOS 操作时必填 | 火山引擎 AK |
| `VOLCENGINE_SECRET_KEY` | TOS 操作时必填 | 火山引擎 SK |
| `VOLCENGINE_SESSION_TOKEN` | 否 | STS 临时凭证 |
| `TOS_REGION` | 否 | TOS Region，默认 `cn-beijing` |
| `TOS_ENDPOINT` | 否 | TOS Endpoint，默认 `tos-cn-beijing.volces.com` |

## CLI 用法

安装后即可使用 `lasutil` 命令：

```bash
lasutil --help
```

### 子命令一览

| 子命令 | 说明 |
|--------|------|
| `submit` | 提交异步任务 |
| `poll` | 查询异步任务状态与结果 |
| `process` | 同步执行任务 |
| `file-upload` | 通过 File API 上传本地文件到 TOS |
| `tos-upload` | 上传本地文件到 TOS |
| `tos-download` | 从 TOS 下载文件到本地 |
| `tos-list` | 列举 TOS 目录文件 |
| `tos-presign` | 生成 TOS 文件预签名 URL |
| `media-duration` | 获取音视频时长及视频分辨率 |
| `media-info` | 获取完整媒体信息（JSON） |
| `image-info` | 获取图片尺寸与编码信息 |
| `pdf-pages` | 获取 PDF 页数 |
| `validate-url` | SSRF 安全检查 URL |

### 常用示例

```bash
# 异步任务：提交 → 查询
lasutil submit las_video_resize '{"video_url":"tos://...","output_tos_dir":"tos://..."}'
lasutil poll las_video_resize <task_id>

# 同步任务
lasutil process las_vlm_video '{"messages":[...],"model_name":"doubao-seed-1.6-vision"}'

# 本地文件上传（返回 presigned_url）
lasutil file-upload ./local_video.mp4

# TOS 操作
lasutil tos-upload local_video.mp4 tos://bucket/prefix/
lasutil tos-download tos://bucket/prefix/video.mp4 ./output.mp4
lasutil tos-presign tos://bucket/prefix/video.mp4 --expires 3600

# 媒体探测
lasutil media-duration tos://bucket/video.mp4
lasutil image-info tos://bucket/image.jpg
lasutil pdf-pages tos://bucket/doc.pdf
```

## 编程接口

在 `v0.2.0` 之后，推荐使用面向对象的 `LASClient`：

```python
from las_sdk import LASClient

# 1. 从环境变量自动读取凭证
client = LASClient.from_env()

# 2. 提交异步任务
response = client.submit(
    operator_id="las_video_resize",
    data={"video_url": "tos://bucket/input.mp4", "codec": "h264"}
)
task_id = response["metadata"]["task_id"]

# 3. 轮询结果
result = client.poll(task_id, "las_video_resize")
if result["metadata"]["task_status"] == "COMPLETED":
    print(result["data"])

# 4. 同步处理
vlm_res = client.process(
    "las_vlm_video",
    {"messages": [...], "model_name": "doubao-seed-1.6-vision"}
)
```

---

## SDK 发布规范

### 发布目录结构

SDK 通过 TOS 发布，目录结构如下：

```
tos://hyy-rd/skills/sdk/
├── las_sdk-0.2.0-py3-none-any.whl      # 历史版本（保留）
├── las_sdk-0.3.0-py3-none-any.whl      # 当前最新版本
├── las_sdk-latest-py3-none-any.whl     # ⭐ 始终指向最新版本
└── manifest.json                        # ⭐ 版本元信息 + 算子变更记录
```

### 发版流程（Checklist）

每次 SDK 发版时，发布脚本必须执行以下步骤：

1. **上传新版 whl**：`las_sdk-{version}-py3-none-any.whl`
2. **覆盖 latest whl**：将新版 whl 复制为 `las_sdk-latest-py3-none-any.whl`
3. **更新 manifest.json**：填写新版本号、发布日期、受影响算子的参数变更

### manifest.json 规范

Skill 在运行时通过 `manifest.json` 感知 SDK 更新和算子参数变更。

**完整示例**：

```json
{
  "sdk_version": "0.3.0",
  "release_date": "2026-03-24",
  "download_url": "https://las-ai-cn-beijing-online.tos-cn-beijing.volces.com/operator_cards_serving/public/skills/sdk/las_sdk-latest-py3-none-any.whl",

  "operators": {
    "las_video_edit": {
      "schema_version": "2025-04-15",
      "changes_since": {
        "2025-03-24": [
          "input: 新增 max_clips (integer, optional) - 限制输出最大片段数",
          "input: 枚举变更 mode - 新增 ultra 选项",
          "output: 新增 clips[].tags (array) - 片段标签列表"
        ]
      }
    },
    "las_asr_pro": {
      "schema_version": "2025-03-01",
      "changes_since": {}
    }
  }
}
```

**字段说明**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `sdk_version` | string | 是 | 当前 SDK 版本号（语义化版本） |
| `release_date` | string | 是 | 发布日期，格式 `YYYY-MM-DD` |
| `download_url` | string | 是 | latest whl 的完整下载 URL |
| `operators` | object | 是 | 各算子的 schema 版本和变更记录 |
| `operators.<id>.schema_version` | string | 是 | 该算子参数定义的最后更新日期 |
| `operators.<id>.changes_since` | object | 是 | key 为基线日期，value 为变更描述数组 |

**`changes_since` 写法约定**：

- key 是变更的基线日期（上一个 schema_version），value 是变更描述列表
- 每条描述格式：`"{input|output}: {变更类型} {字段名} ({类型}, {required|optional}) - {说明}"`
- 变更类型关键词：`新增` / `移除` / `类型变更` / `枚举变更` / `默认值变更`
- 无参数变更的算子：`changes_since` 为空对象 `{}`
- 保留最近 3 个版本的变更记录，更早的可清除

**标准写法示例**：

```
"input: 新增 max_clips (integer, optional) - 限制输出最大片段数"
"input: 移除 legacy_mode (string) - 已废弃"
"input: 枚举变更 mode - 新增 ultra 选项"
"input: 默认值变更 min_segment_duration - 1 → 2"
"output: 新增 clips[].tags (array) - 片段标签列表"
"output: 类型变更 duration - integer → float"
```

### Skill 侧消费方式

各 Skill 的 SKILL.md Step 1 会在运行时自动执行以下检查：

```bash
# 1. 拉取 manifest
manifest=$(curl -sf "$manifest_url" || echo '{}')

# 2. 比较 SDK 版本，不一致则自动升级
local_ver=$(lasutil --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' || echo "0.0.0")
remote_ver=$(echo "$manifest" | jq -r '.sdk_version // "unknown"')
if [ "$local_ver" != "$remote_ver" ]; then
  pip install --upgrade "$(echo "$manifest" | jq -r '.download_url')"
fi

# 3. 检查当前算子的参数变更，有变更则提示用户
op_changes=$(echo "$manifest" | jq -r \
  '.operators.<operator_id>.changes_since // {} | to_entries[] | "  自 \(.key) 起: \(.value[])"' 2>/dev/null)
if [ -n "$op_changes" ]; then
  echo "⚠️ 算子参数有更新:"
  echo "$op_changes"
fi
```

> 如果 manifest.json 请求失败（网络问题），Skill 会静默跳过检查，使用本地已安装的 SDK 继续执行。
