feat(sdk): support inference_v3 config_file mount

V2arK · V2arK · commit 41a72f9d35ba · 2026-05-21T14:47:13.000-04:00
Bump platform-api-python-client to 4.10.0 so ConfigFileMount is
importable, and add a thin helper in centml/sdk/utils/config_file.py
that reads a file off disk and returns a populated ConfigFileMount.
Example create_inference.py updated to show the helper in context.

Server (platform PRs #3656 and #3667) owns all field-level validation
(64 KiB content cap, filename charset, mount_path rules); the helper
deliberately stays validation-free so the SDK does not drift when
server limits change.

Signed-off-by: Honglin Cao &lt;hocao@nvidia.com&gt;
diff --git a/centml/sdk/utils/config_file.py b/centml/sdk/utils/config_file.py
@@ -0,0 +1,13 @@
+import os
+from typing import Optional
+
+from platform_api_python_client import ConfigFileMount
+
+
+# Load a file off disk into a ConfigFileMount. Field-level validation
+# (size cap, filename charset, mount_path rules) is intentionally left
+# to the API so SDK doesn't drift when server limits change.
+def load_config_file_mount(path: str, mount_path: str, filename: Optional[str] = None) -> ConfigFileMount:
+    with open(path, "r", encoding="utf-8") as f:
+        content = f.read()
+    return ConfigFileMount(filename=filename or os.path.basename(path), mount_path=mount_path, content=content)
diff --git a/docs/superpowers/specs/2026-05-21-sdk-config-file-support-design.md b/docs/superpowers/specs/2026-05-21-sdk-config-file-support-design.md
@@ -0,0 +1,265 @@
+# SDK 支持 inference_v3 `config_file`
+
+日期：2026-05-21
+仓库：`centml-python-client`
+新建分支：`honglin/sdk-config-file-support`
+
+## 背景
+
+平台侧两个 PR 为 `inference_v3` deployment 增加了可选的单文件挂载支持：
+
+- [`#3656`](https://github.com/CentML/platform/pull/3656) —— schema、catalog、
+  generated clients、UI 全套：`CreateInferenceV3DeploymentRequest.config_file` 和
+  `GetInferenceV3DeploymentResponse.config_file` 携带一个可选的
+  `ConfigFileMount{filename, mount_path, content}`。
+- [`#3667`](https://github.com/CentML/platform/pull/3667) —— 收紧 server 端校验：
+  `content` 字段 64 KiB UTF-8 字节上限、`mount_path` 拒绝 `..` 段、
+  PATH_MAX 按 UTF-8 字节计。
+
+`centml-python-client` SDK 当前在 `requirements.txt` pin 了
+`platform-api-python-client==4.9.0`，早于这两个 PR。
+PyPI 现在 latest 是 `platform-api-python-client==4.10.0`
+（2026-05-21 用 `pip index versions` 验证过），其中含
+`platform_api_python_client/models/config_file_mount.py`
+（通过解包 wheel 验证）。
+
+由于 pin 版本里没有这个 model，SDK 用户今天没法传 `config_file`。
+bump pin 之后，`config_file` 作为 `CreateInferenceV3DeploymentRequest`
+的一个透传字段就能用，SDK 代码无需任何变动 —— 但每次使用都需要用户自己
+从磁盘读文件构造 `ConfigFileMount`，这个动作是高频重复的。
+
+## 目标
+
+用最小表面积让 `config_file` 在 SDK 中成为一等公民：
+
+1. Bump generated client pin，让 `ConfigFileMount` 可被 import。
+2. 加一个轻量 helper，从磁盘读文件并返回填好的 `ConfigFileMount`，
+   匹配仓内 `centml/sdk/utils/client_certs.py` 现有 pattern。
+3. 更新 canonical example，让用户看到 helper 的实际用法。
+
+非目标：
+
+- 不加 CLI 命令（2026-05-21 用户确认 —— CLI 延后）。
+- 不在 client 侧重复 server 校验（size cap、path 规则）。
+  API 是 source of truth，server 限制可能变。
+- 不对 generated `ConfigFileMount` 做 wrapper / subclass
+  （仓内没有 subclass generated model 的先例）。
+- 不在 `centml.sdk` 顶层 re-export：与
+  `centml/sdk/utils/client_certs.py` 一致，走 qualified path 导入。
+
+## 沿用的仓内既有约定
+
+- `centml/sdk/utils/client_certs.py` —— free function（动词命名，如
+  `generate_ca_client_triplet`、`save_pem_file`），不对 generated model
+  做 class wrapping，函数上方 `#` 块注释解释 *why*。
+- `examples/sdk/create_inference.py` —— 单 `main()`，文件顶部
+  `import centml` + `from centml.sdk.api import get_centml_client` +
+  `from centml.sdk import ...`，文件末尾用三引号注释 pause/delete 示例。
+- `requirements.txt` —— 严格 `==` pinning。
+- `scripts/format.sh` —— Black，`--skip-string-normalization`，
+  `--skip-magic-trailing-comma`，`--line-length 120`。
+- `tests/` —— 文件名 `test_<area>.py`，pytest，conftest 带 `--sanity` 选项；
+  无 E2E 网络调用。
+
+## 设计
+
+### 1. 依赖 bump
+
+`requirements.txt`：
+
+```diff
+-platform-api-python-client==4.9.0
++platform-api-python-client==4.10.0
+```
+
+理由：4.10.0 是 PyPI 当前 latest，同时包含 feature PR #3656 和校验收紧 PR
+#3667。已通过下载 wheel 验证。
+
+无其他依赖变动。`setup.py` 从 `requirements.txt` 读，无需修改。
+
+### 2. Helper
+
+新文件 `centml/sdk/utils/config_file.py`：
+
+```python
+import os
+from typing import Optional
+
+from platform_api_python_client import ConfigFileMount
+
+
+# Load a file off disk into a ConfigFileMount. Field-level validation
+# (size cap, filename charset, mount_path rules) is intentionally left
+# to the API so SDK doesn't drift when server limits change.
+def load_config_file_mount(path: str, mount_path: str, filename: Optional[str] = None) -> ConfigFileMount:
+    with open(path, "r", encoding="utf-8") as f:
+        content = f.read()
+    return ConfigFileMount(
+        filename=filename or os.path.basename(path),
+        mount_path=mount_path,
+        content=content,
+    )
+```
+
+设计决定，附理由：
+
+- **Free function，不是 subclass。** 匹配 `client_certs.py`；仓内没有
+  subclass generated client model 的先例。
+- **直接返回 generated `ConfigFileMount`。** Type signature 直接 drop in
+  `CreateInferenceV3DeploymentRequest(config_file=...)`，无需转换。
+- **`filename` 可选，默认 `os.path.basename(path)`。** 常见情形就是
+  把 `nginx.conf` 挂载为 `nginx.conf`；需要 rename 时显式传。
+- **`mount_path` 无默认值。** 容器内挂载位置正是这个字段的存在意义 ——
+  没有合理默认。
+- **不做 client-side 校验。** 2026-05-21 用户确认：API 是 source of
+  truth，server 侧限制（如 64 KiB content 上限）可能演化。Server 在
+  超限时返回 422 并带具体字节数（见 #3667）。
+- **UTF-8 文本读取。** Server 契约是 `content: str`。二进制 config
+  不在当前 platform schema 范围内。
+- **不改 `centml/sdk/utils/__init__.py`。** 该文件当前为空；
+  消费者用 qualified path 导入
+  `from centml.sdk.utils.config_file import load_config_file_mount`，
+  与 `client_certs.py` 的消费方式一致。
+
+函数命名 `load_config_file_mount`。"Load" 是"从磁盘读+构造"的精确动词；
+`build_*` 因为项目规则偏好精确动词、不推荐 `build` 而被淘汰。
+
+### 3. Example 更新
+
+`examples/sdk/create_inference.py` —— 增加 helper import，并在原有 request
+上加 `config_file=...` 字段。其他字段全部保留。最终形态：
+
+```python
+import centml
+from centml.sdk.api import get_centml_client
+from centml.sdk import DeploymentType, CreateInferenceV3DeploymentRequest, UserVaultType
+from centml.sdk.utils.config_file import load_config_file_mount
+
+
+def main():
+    with get_centml_client() as cclient:
+        certs = cclient.get_user_vault(UserVaultType.CERTIFICATES)
+
+        request = CreateInferenceV3DeploymentRequest(
+            name="nginx",
+            cluster_id=1000,
+            hardware_instance_id=1000,
+            image_url="nginxinc/nginx-unprivileged",
+            port=8080,
+            min_replicas=1,
+            max_replicas=3,
+            initial_replicas=1,
+            endpoint_certificate_authority=certs["my_cert"],
+            max_surge=1,
+            max_unavailable=0,
+            healthcheck="/",
+            concurrency=10,
+            # Helper reads ./nginx.conf and wraps it; pass an inline
+            # ConfigFileMount(filename=..., mount_path=..., content=...) if
+            # the content is already in memory.
+            config_file=load_config_file_mount(
+                path="./nginx.conf",
+                mount_path="/etc/nginx/conf.d/default.conf",
+            ),
+        )
+        response = cclient.create_inference(request)
+        print("Create deployment response: ", response)
+
+        deployment = cclient.get_inference(response.id)
+        print("Deployment details: ", deployment)
+
+        '''
+        ### Pause the deployment
+        cclient.pause(deployment.id)
+
+        ### Delete the deployment
+        cclient.delete(deployment.id)
+        '''
+
+
+if __name__ == "__main__":
+    main()
+```
+
+末尾三引号 pause/delete 块原样保留。
+
+### 4. 测试
+
+新文件 `tests/test_sdk_config_file_helper.py`。测试先于 helper 实现写
+（按项目 Prime Directive #2 的 TDD 要求）。无网络、无 platform mock ——
+只用 `tmp_path` fixture + pytest。
+
+测试用例（每个一个 `def test_*`）：
+
+1. **`test_default_filename_from_basename`**：写 `tmp_path/nginx.conf`，
+   调 `load_config_file_mount(path, "/etc/nginx/conf.d/default.conf")`，
+   断言 `mount.filename == "nginx.conf"`、`mount.content == <文件内容>`、
+   `mount.mount_path == "/etc/nginx/conf.d/default.conf"`。
+
+2. **`test_explicit_filename_overrides_basename`**：写 `tmp_path/local.txt`，
+   传 `filename="remote.conf"`，断言 `mount.filename == "remote.conf"`，
+   content / mount_path 保持。
+
+3. **`test_utf8_multibyte_content_roundtrips`**：写一个含 CJK 字符的文件，
+   断言 `mount.content` 与原始字符串相等（catch 错误的 binary-mode 读）。
+
+4. **`test_missing_file_raises_filenotfound`**：传一个不存在的 path，
+   断言 `FileNotFoundError`。明确 helper *不* 吞掉 I/O 错误。
+
+测试不断言 server 侧限制（size cap、mount_path 规则）—— 那些是 server
+契约，不是 helper 的职责（见设计 / "不做 client-side 校验"）。
+
+### 5. 范围之外
+
+- 不加 inference create/update 的 CLI 命令（按用户 2026-05-21 决定延后）。
+- 不动 `README.md`，除非已有 SDK 用法 doc 需要更新。
+- 不动 `centml/sdk/api.py` —— `create_inference` / `update_inference`
+  已经吃 `CreateInferenceV3DeploymentRequest`，pass-through 就够用。
+- 不加 in-memory helper（如 `load_config_file_mount_from_bytes`）；generated
+  `ConfigFileMount(...)` 构造器对这种 case 已经够简单。
+
+## 文件级变更汇总
+
+| 文件 | 变更 |
+| --- | --- |
+| `requirements.txt` | bump `platform-api-python-client` `4.9.0` → `4.10.0` |
+| `centml/sdk/utils/config_file.py` | 新文件（约 15 行含注释 + import） |
+| `examples/sdk/create_inference.py` | 加 import + `config_file=load_config_file_mount(...)` |
+| `tests/test_sdk_config_file_helper.py` | 新文件，4 个 test（TDD：先写） |
+
+不动任何其他文件。
+
+## 验证计划
+
+declare done 之前：
+
+1. `pip install -r requirements.txt` 在新 pin 下成功。
+2. `python -c "from centml.sdk.utils.config_file import load_config_file_mount; print(load_config_file_mount.__doc__ or 'ok')"` 没有 ImportError。
+3. `cd tests && pytest --sanity` 通过；新加的 4 个 test 在 run output
+   中可见。
+4. `./scripts/format.sh --check` 和 `./scripts/lint.sh` 干净。
+5. `./scripts/typecheck.sh` 干净（`Optional[str]` 已是仓内风格）。
+6. Manual smoke（可选，dev cluster 在手时）：在 dev 跑修改后的
+   `examples/sdk/create_inference.py`，带一个小的本地 `nginx.conf` 文件，
+   确认 `cclient.get_inference(id).config_file` 与发出的内容一致。
+
+## Commit 计划
+
+单个 commit，conventional commits 风格，subject ≤72 字符：
+
+```
+feat(sdk): support inference_v3 config_file mount
+```
+
+Body：简要引用平台 PR #3656/#3667 和三处改动（bump、helper、example）。
+带 `Signed-off-by: Honglin Cao <hocao@nvidia.com>`。
+禁 `git add -A` / `git add .` —— 四个文件单独 `git add`。
+
+## 引用
+
+- 平台 PR [#3656](https://github.com/CentML/platform/pull/3656) —— feature
+- 平台 PR [#3667](https://github.com/CentML/platform/pull/3667) —— 校验收紧
+- 仓内风格先例：`centml/sdk/utils/client_certs.py`
+- Example 先例：`examples/sdk/create_inference.py`
+- PyPI 验证：`platform-api-python-client==4.10.0` wheel 含
+  `models/config_file_mount.py`（2026-05-21 验证）
diff --git a/examples/sdk/create_inference.py b/examples/sdk/create_inference.py
@@ -1,6 +1,7 @@
 import centml
 from centml.sdk.api import get_centml_client
 from centml.sdk import DeploymentType, CreateInferenceV3DeploymentRequest, UserVaultType
+from centml.sdk.utils.config_file import load_config_file_mount
 
 
 def main():
@@ -22,6 +23,13 @@ def main():
             max_unavailable=0,  # Keep all pods available during updates
             healthcheck="/",
             concurrency=10,
+            # Helper reads ./nginx.conf and wraps it; pass an inline
+            # ConfigFileMount(filename=..., mount_path=..., content=...) if
+            # the content is already in memory.
+            config_file=load_config_file_mount(
+                path="./nginx.conf",
+                mount_path="/etc/nginx/conf.d/default.conf",
+            ),
         )
         response = cclient.create_inference(request)
         print("Create deployment response: ", response)
diff --git a/requirements.txt b/requirements.txt
@@ -5,4 +5,4 @@ pyjwt>=2.8.0
 cryptography==46.0.7
 websockets>=16.0
 pyte>=0.8.0
-platform-api-python-client==4.9.0
+platform-api-python-client==4.10.0
diff --git a/tests/test_sdk_config_file_helper.py b/tests/test_sdk_config_file_helper.py
@@ -0,0 +1,41 @@
+"""Tests for centml.sdk.utils.config_file.load_config_file_mount."""
+
+import pytest
+
+from centml.sdk.utils.config_file import load_config_file_mount
+
+
+def test_default_filename_from_basename(tmp_path):
+    src = tmp_path / "nginx.conf"
+    src.write_text("server { listen 80; }\n")
+
+    mount = load_config_file_mount(str(src), "/etc/nginx/conf.d/default.conf")
+
+    assert mount.filename == "nginx.conf"
+    assert mount.mount_path == "/etc/nginx/conf.d/default.conf"
+    assert mount.content == "server { listen 80; }\n"
+
+
+def test_explicit_filename_overrides_basename(tmp_path):
+    src = tmp_path / "local.txt"
+    src.write_text("payload")
+
+    mount = load_config_file_mount(str(src), "/app/etc/remote.conf", filename="remote.conf")
+
+    assert mount.filename == "remote.conf"
+    assert mount.mount_path == "/app/etc/remote.conf"
+    assert mount.content == "payload"
+
+
+def test_utf8_multibyte_content_roundtrips(tmp_path):
+    src = tmp_path / "i18n.conf"
+    src.write_text("配置内容 = 测试\n", encoding="utf-8")
+
+    mount = load_config_file_mount(str(src), "/etc/app/i18n.conf")
+
+    assert mount.content == "配置内容 = 测试\n"
+
+
+def test_missing_file_raises_filenotfound(tmp_path):
+    with pytest.raises(FileNotFoundError):
+        load_config_file_mount(str(tmp_path / "does-not-exist.conf"), "/etc/x")
