ai-center-runtime 0.2.0__tar.gz

ai_center_runtime-0.2.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: ai-center-runtime
+Version: 0.2.0
+Summary: Relay-only model access SDK for AI Center applications (invocation binding, allowlist, stable errors)
+Author: 01JohnMa
+Project-URL: Homepage, https://github.com/01JohnMa/ai_center
+Project-URL: Changelog, https://github.com/01JohnMa/ai_center/commits/main/packages/ai-center-runtime
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: openai==2.54.0
+Requires-Dist: httpx==0.28.1
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.115; extra == "fastapi"
+
+# ai-center-runtime
+
+Python 应用接入 AI Center 模型网关的最小 SDK。
+
+**Relay-only 合同（ADR-0015，2026-09-29 修订）**：应用不直连 LiteLLM，也不手工拼装归因。
+部署时平台注入三元组环境变量，应用把模型请求发到平台 Relay，归因（spend logs
+metadata）由平台在转发时注入，ModelCall/Token/费用由 AI Center 对账生成。
+
+| 环境变量 | 含义 |
+|---|---|
+| `AI_CENTER_MODEL_GATEWAY_URL_TEMPLATE` | 含 `{invocation_id}` 占位符的 Relay 端点模板 |
+| `AI_CENTER_RUNTIME_CREDENTIAL` | per-Deployment 运行时凭据（随部署轮换） |
+| `AI_CENTER_MODEL_OPERATIONS` | 允许的 operation 白名单（逗号分隔；缺省一律拒绝） |
+
+## 安装
+
+从仓库根目录执行（当前无需发布 PyPI）：
+
+```sh
+uv pip install ./packages/ai-center-runtime
+```
+
+## 接入：异步 Job 中绑定 Invocation，再调用模型
+
+```python
+from ai_center_runtime import (
+    PlatformModelClient, PlatformModelError,
+    bind_invocation, model_access_mode,
+)
+
+# 1) 部署受理时把平台 Invocation 绑定到当前任务上下文（如异步 Job）。
+binding = bind_invocation(platform_invocation_id)
+try:
+    if model_access_mode() != "relay":
+        raise RuntimeError("平台模型访问未配置 Relay；direct 仅限本地开发")
+
+    # 2) 客户端读取三元组环境变量；白名单外的 operation 在发请求前失败。
+    with PlatformModelClient() as models:
+        answer = models.chat_completion(
+            [{"role": "user", "content": "你好"}],
+            model="deepseek-flash",
+            json_mode=True,
+        )
+        print(answer["choices"][0]["message"]["content"])
+
+        vectors = models.text_embeddings(["一段文本"], model="text-embedding")
+finally:
+    binding.restore()
+```
+
+要点：
+
+- **FastAPI 一行接入**（可选依赖）：同步接口不需要手写"读 header + bind +
+  try/finally restore"——用依赖注入器，请求进入自动绑定、响应后自动解绑：
+
+  ```python
+  from fastapi import Depends
+  from ai_center_runtime import model_invocation, PlatformModelClient
+
+  @app.post("/extract")
+  async def extract(req: ExtractRequest, _b=Depends(model_invocation())):
+      # 本 handler 内的 Relay 调用自动携带 Invocation
+      with PlatformModelClient() as models:
+          return models.chat_completion([...], model="deepseek-flash")
+  ```
+
+  安装：`pip install 'ai-center-runtime[fastapi]'`。缺
+  `x-ai-center-invocation-id` 头时返回 422；`model_invocation(required=False)`
+  放行无 Invocation 请求（调用点 fail-closed 不变）。
+
+- **mode 三态，绝不回退**：`model_access_mode()` 返回 `relay` / `direct` /
+  `unconfigured`；`direct` 只有应用显式设置 `AI_CENTER_LLM_MODE=direct`（本地开发）
+  时成立，平台从不注入它。
+- **fail closed**：白名单缺失或 operation 越界抛 `MODEL_CAPABILITY_UNAVAILABLE`；
+  未绑定 Invocation 抛 `MODEL_INVOCATION_MISSING`。构造
+  `PlatformModelClient()` 本身就是模式检查（未配置时构造即失败），无需再手写
+  mode 判断。
+- **稳定错误**：`PlatformModelError.reason` ∈ `MODEL_CAPABILITY_UNAVAILABLE` /
+  `MODEL_INVOCATION_MISSING` / `MODEL_ACCESS_EXPIRED`（异步窗口过期）/
+  `MODEL_TIMEOUT` / `MODEL_UPSTREAM_ERROR`；`status` 携带 HTTP 状态。
+- **logical_call_id**：默认按 `{invocation_id}:{scope}:{sha256[:24]}` 生成并经
+  `x-request-id` 透传；同一逻辑调用的重试应显式传同一个 `logical_call_id`。
+- **OpenAI 兼容生态**：`relay_connection()` 返回 `{"base_url", "api_key"}`，
+  可直接喂给 `openai.OpenAI(...)`、llama_index `OpenAI(...)` 等。
+
+## 旧合同（Deprecated）
+
+`InvocationContext` / `ModelClient` 是直连 LiteLLM 时代的合同：平台已不再注入
+`LITELLM_BASE_URL` / `LITELLM_API_KEY`，新应用禁止使用；它们仅为尚未迁移的
+历史应用保留，迁移路径是把 `InvocationContext.from_headers(...)` +
+`ModelClient.from_runtime_context(...)` 替换为 `bind_invocation(...)` +
+`PlatformModelClient(...)`。
+
+## 限制与证据边界
+
+- 只支持 blocking JSON（chat.completions / embeddings）；SSE 与
+  responses 端点的客户端封装暂未提供。同步调用用 `PlatformModelClient`，
+  异步应用（FastAPI 路由、async Worker）用 `AsyncPlatformModelClient`，
+  两者接口语义一致。
+- 不自动重试、不跟随重定向；Provider 路由与重试由 LiteLLM owner 负责。
+- 归因字段由平台 Relay 注入，SDK 与应用都不能覆盖；应用也不应伪造
+  `x-ai-center-*` header。
+- SDK 不能在恶意代码面前充当沙箱；凭据模型限制、Relay 窗口与白名单、
+  Runtime 网络隔离负责服务端强制治理。
+
+## 验证
+
+```sh
+PYTHONPATH=packages/ai-center-runtime/src uv run --project packages/ai-center-runtime \
+  python -m unittest discover -s packages/ai-center-runtime/tests
+```
+
+协议测试通过 httpx MockTransport 校验三元组解析、模板物化、白名单 fail-closed、
+错误映射与绑定隔离，不需要真实平台。真实链路探针见 `scripts/smoke_relay.py`。
+
+合同来源：[ADR 0013](../../docs/adr/0013-runtime-v2-unified-invocation-and-usage.md)、
+[ADR 0015](../../docs/adr/0015-platform-model-gateway-relay.md)。

ai_center_runtime-0.2.0/README.md

@@ -0,0 +1,117 @@
+# ai-center-runtime
+
+Python 应用接入 AI Center 模型网关的最小 SDK。
+
+**Relay-only 合同（ADR-0015，2026-09-29 修订）**：应用不直连 LiteLLM，也不手工拼装归因。
+部署时平台注入三元组环境变量，应用把模型请求发到平台 Relay，归因（spend logs
+metadata）由平台在转发时注入，ModelCall/Token/费用由 AI Center 对账生成。
+
+| 环境变量 | 含义 |
+|---|---|
+| `AI_CENTER_MODEL_GATEWAY_URL_TEMPLATE` | 含 `{invocation_id}` 占位符的 Relay 端点模板 |
+| `AI_CENTER_RUNTIME_CREDENTIAL` | per-Deployment 运行时凭据（随部署轮换） |
+| `AI_CENTER_MODEL_OPERATIONS` | 允许的 operation 白名单（逗号分隔；缺省一律拒绝） |
+
+## 安装
+
+从仓库根目录执行（当前无需发布 PyPI）：
+
+```sh
+uv pip install ./packages/ai-center-runtime
+```
+
+## 接入：异步 Job 中绑定 Invocation，再调用模型
+
+```python
+from ai_center_runtime import (
+    PlatformModelClient, PlatformModelError,
+    bind_invocation, model_access_mode,
+)
+
+# 1) 部署受理时把平台 Invocation 绑定到当前任务上下文（如异步 Job）。
+binding = bind_invocation(platform_invocation_id)
+try:
+    if model_access_mode() != "relay":
+        raise RuntimeError("平台模型访问未配置 Relay；direct 仅限本地开发")
+
+    # 2) 客户端读取三元组环境变量；白名单外的 operation 在发请求前失败。
+    with PlatformModelClient() as models:
+        answer = models.chat_completion(
+            [{"role": "user", "content": "你好"}],
+            model="deepseek-flash",
+            json_mode=True,
+        )
+        print(answer["choices"][0]["message"]["content"])
+
+        vectors = models.text_embeddings(["一段文本"], model="text-embedding")
+finally:
+    binding.restore()
+```
+
+要点：
+
+- **FastAPI 一行接入**（可选依赖）：同步接口不需要手写"读 header + bind +
+  try/finally restore"——用依赖注入器，请求进入自动绑定、响应后自动解绑：
+
+  ```python
+  from fastapi import Depends
+  from ai_center_runtime import model_invocation, PlatformModelClient
+
+  @app.post("/extract")
+  async def extract(req: ExtractRequest, _b=Depends(model_invocation())):
+      # 本 handler 内的 Relay 调用自动携带 Invocation
+      with PlatformModelClient() as models:
+          return models.chat_completion([...], model="deepseek-flash")
+  ```
+
+  安装：`pip install 'ai-center-runtime[fastapi]'`。缺
+  `x-ai-center-invocation-id` 头时返回 422；`model_invocation(required=False)`
+  放行无 Invocation 请求（调用点 fail-closed 不变）。
+
+- **mode 三态，绝不回退**：`model_access_mode()` 返回 `relay` / `direct` /
+  `unconfigured`；`direct` 只有应用显式设置 `AI_CENTER_LLM_MODE=direct`（本地开发）
+  时成立，平台从不注入它。
+- **fail closed**：白名单缺失或 operation 越界抛 `MODEL_CAPABILITY_UNAVAILABLE`；
+  未绑定 Invocation 抛 `MODEL_INVOCATION_MISSING`。构造
+  `PlatformModelClient()` 本身就是模式检查（未配置时构造即失败），无需再手写
+  mode 判断。
+- **稳定错误**：`PlatformModelError.reason` ∈ `MODEL_CAPABILITY_UNAVAILABLE` /
+  `MODEL_INVOCATION_MISSING` / `MODEL_ACCESS_EXPIRED`（异步窗口过期）/
+  `MODEL_TIMEOUT` / `MODEL_UPSTREAM_ERROR`；`status` 携带 HTTP 状态。
+- **logical_call_id**：默认按 `{invocation_id}:{scope}:{sha256[:24]}` 生成并经
+  `x-request-id` 透传；同一逻辑调用的重试应显式传同一个 `logical_call_id`。
+- **OpenAI 兼容生态**：`relay_connection()` 返回 `{"base_url", "api_key"}`，
+  可直接喂给 `openai.OpenAI(...)`、llama_index `OpenAI(...)` 等。
+
+## 旧合同（Deprecated）
+
+`InvocationContext` / `ModelClient` 是直连 LiteLLM 时代的合同：平台已不再注入
+`LITELLM_BASE_URL` / `LITELLM_API_KEY`，新应用禁止使用；它们仅为尚未迁移的
+历史应用保留，迁移路径是把 `InvocationContext.from_headers(...)` +
+`ModelClient.from_runtime_context(...)` 替换为 `bind_invocation(...)` +
+`PlatformModelClient(...)`。
+
+## 限制与证据边界
+
+- 只支持 blocking JSON（chat.completions / embeddings）；SSE 与
+  responses 端点的客户端封装暂未提供。同步调用用 `PlatformModelClient`，
+  异步应用（FastAPI 路由、async Worker）用 `AsyncPlatformModelClient`，
+  两者接口语义一致。
+- 不自动重试、不跟随重定向；Provider 路由与重试由 LiteLLM owner 负责。
+- 归因字段由平台 Relay 注入，SDK 与应用都不能覆盖；应用也不应伪造
+  `x-ai-center-*` header。
+- SDK 不能在恶意代码面前充当沙箱；凭据模型限制、Relay 窗口与白名单、
+  Runtime 网络隔离负责服务端强制治理。
+
+## 验证
+
+```sh
+PYTHONPATH=packages/ai-center-runtime/src uv run --project packages/ai-center-runtime \
+  python -m unittest discover -s packages/ai-center-runtime/tests
+```
+
+协议测试通过 httpx MockTransport 校验三元组解析、模板物化、白名单 fail-closed、
+错误映射与绑定隔离，不需要真实平台。真实链路探针见 `scripts/smoke_relay.py`。
+
+合同来源：[ADR 0013](../../docs/adr/0013-runtime-v2-unified-invocation-and-usage.md)、
+[ADR 0015](../../docs/adr/0015-platform-model-gateway-relay.md)。

ai_center_runtime-0.2.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ai-center-runtime"
+version = "0.2.0"
+description = "Relay-only model access SDK for AI Center applications (invocation binding, allowlist, stable errors)"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["openai==2.54.0", "httpx==0.28.1"]
+authors = [{ name = "01JohnMa" }]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/01JohnMa/ai_center"
+Changelog = "https://github.com/01JohnMa/ai_center/commits/main/packages/ai-center-runtime"
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.115"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I", "UP"]

ai_center_runtime-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ai_center_runtime-0.2.0/src/ai_center_runtime/__init__.py

@@ -0,0 +1,284 @@
+"""AI Center Runtime SDK.
+
+Relay-only 合同（ADR-0015 2026-09-29 修订）是应用接入平台模型访问的唯一
+方式：部署注入三元组环境变量，应用通过 :mod:`ai_center_runtime.relay` 的
+``bind_invocation`` + ``PlatformModelClient`` 调用模型，归因由平台 Relay 注入。
+
+``InvocationContext`` / ``ModelClient`` 是直连 LiteLLM 时代的旧合同，保留
+仅供历史应用迁移；新应用不要使用。
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import SimpleNamespace
+from urllib.parse import urlsplit
+
+import httpx
+from openai import OpenAI
+
+from .fastapi_integration import INVOCATION_HEADER, model_invocation  # 不在顶层导入 fastapi
+from .relay import (
+    GATEWAY_URL_TEMPLATE_ENV,
+    LLM_MODE_ENV,
+    MODEL_OPERATIONS_ENV,
+    RUNTIME_CREDENTIAL_ENV,
+    AsyncPlatformModelClient,
+    PlatformModelClient,
+    PlatformModelError,
+    bind_invocation,
+    current_invocation_id,
+    model_access_mode,
+    restore_invocation,
+)
+
+__all__ = [
+    "GATEWAY_URL_TEMPLATE_ENV",
+    "INVOCATION_HEADER",
+    "LLM_MODE_ENV",
+    "MODEL_OPERATIONS_ENV",
+    "RUNTIME_CREDENTIAL_ENV",
+    "AsyncPlatformModelClient",
+    "InvocationContext",
+    "ModelAccessError",
+    "ModelClient",
+    "PlatformModelClient",
+    "PlatformModelError",
+    "bind_invocation",
+    "current_invocation_id",
+    "model_access_mode",
+    "model_invocation",
+    "restore_invocation",
+]
+
+_OPERATIONS = frozenset({"chat.completions", "responses", "embeddings"})
+_REFERENCE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:-]{0,255}\Z")
+_MODEL = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:@/-]{0,255}\Z")
+_TRACEPARENT = re.compile(r"00-(?!0{32}-)[0-9a-f]{32}-(?!0{16}-)[0-9a-f]{16}-[0-9a-f]{2}\Z")
+_RESERVED = frozenset(
+    {
+        "schema_version",
+        "application_id",
+        "application_version_id",
+        "invocation_id",
+        "caller_id",
+        "trace_id",
+        "traceparent",
+        "operation",
+        "component",
+        "session_id",
+        "litellm_session_id",
+        "request_id",
+        "ai_center",
+        "spend_logs_metadata",
+        "api_key",
+        "base_url",
+        "litellm_params",
+    }
+)
+
+
+class ModelAccessError(ValueError):
+    """Invalid context/config/request. Raised before any model HTTP request."""
+
+
+def _reference(value: object) -> bool:
+    return isinstance(value, str) and _REFERENCE.fullmatch(value) is not None
+
+
+@dataclass(frozen=True)
+class InvocationContext:
+    """Provided by the trusted Runtime ingress, never by application business input."""
+
+    invocation_id: str
+    application_id: str
+    application_version_id: str
+    caller_id: str
+    traceparent: str
+
+    def __post_init__(self):
+        if not all(
+            _reference(v)
+            for v in (
+                self.invocation_id,
+                self.application_id,
+                self.application_version_id,
+                self.caller_id,
+            )
+        ):
+            raise ModelAccessError("Invalid Gateway invocation identity")
+        if not isinstance(self.traceparent, str) or not _TRACEPARENT.fullmatch(self.traceparent):
+            raise ModelAccessError("A valid Gateway traceparent is required")
+
+    @property
+    def trace_id(self) -> str:
+        return self.traceparent.split("-")[1]
+
+    @classmethod
+    def from_headers(cls, headers: Mapping[str, str]) -> InvocationContext:
+        """Use only after ingress guarantees the request is from AI Center Gateway."""
+        normalized = {}
+        for name, value in headers.items():
+            name = name.lower()
+            if name in normalized:
+                raise ModelAccessError("Duplicate Gateway header")
+            normalized[name] = value
+        try:
+            return cls(
+                invocation_id=normalized["x-ai-center-invocation-id"],
+                application_id=normalized["x-ai-center-application-id"],
+                application_version_id=normalized["x-ai-center-application-version-id"],
+                caller_id=normalized["x-ai-center-caller-id"],
+                traceparent=normalized["traceparent"],
+            )
+        except KeyError:
+            raise ModelAccessError("Gateway invocation headers are incomplete") from None
+
+
+class _Create:
+    def __init__(self, owner, operation, create):
+        self._owner, self._operation, self._create = owner, operation, create
+
+    def create(self, *, model: str, **kwargs):
+        return self._create(**self._owner._request(self._operation, model, kwargs))
+
+
+class ModelClient:
+    """Blocking JSON only. Owns one OpenAI client for one immutable Invocation Context.
+
+    Deprecated: 直连 LiteLLM 的旧合同（平台不再注入 ``LITELLM_BASE_URL``）。
+    新应用使用 :class:`ai_center_runtime.relay.PlatformModelClient`。
+    """
+
+    @classmethod
+    def from_runtime_context(
+        cls,
+        context: InvocationContext,
+        *,
+        base_url: str,
+        api_key: str,
+        timeout: float = 30,
+        transport: httpx.BaseTransport | None = None,
+    ) -> ModelClient:
+        return cls(
+            context,
+            base_url=base_url,
+            api_key=api_key,
+            timeout=timeout,
+            transport=transport,
+        )
+
+    def __init__(
+        self,
+        context: InvocationContext,
+        *,
+        base_url: str,
+        api_key: str,
+        timeout: float = 30,
+        transport: httpx.BaseTransport | None = None,
+    ):
+        if not isinstance(context, InvocationContext):
+            raise ModelAccessError("Trusted InvocationContext is required")
+        if os.environ.get("OPENAI_CUSTOM_HEADERS"):
+            raise ModelAccessError("Unset OPENAI_CUSTOM_HEADERS; Runtime headers are controlled")
+        if (
+            not isinstance(api_key, str)
+            or not api_key.strip()
+            or any(ord(c) < 33 or ord(c) > 126 for c in api_key)
+        ):
+            raise ModelAccessError("Runtime Integration Credential is required")
+        url = urlsplit(base_url)
+        if (
+            url.scheme not in {"http", "https"}
+            or not url.hostname
+            or url.username
+            or url.password
+            or url.query
+            or url.fragment
+        ):
+            raise ModelAccessError("An explicit LiteLLM base URL is required")
+        if not 0 < timeout <= 120:
+            raise ModelAccessError("Invalid model timeout")
+        self._context = context
+        self._model_request_count = 0
+        self._client = OpenAI(
+            organization="",
+            project="",
+            base_url=base_url.rstrip("/") + "/",
+            api_key=api_key,
+            max_retries=0,
+            timeout=timeout,
+            http_client=httpx.Client(
+                transport=transport,
+                timeout=timeout,
+                follow_redirects=False,
+                trust_env=False,
+            ),
+        )
+        self.chat = SimpleNamespace(
+            completions=_Create(self, "chat.completions", self._client.chat.completions.create)
+        )
+        self.responses = _Create(self, "responses", self._client.responses.create)
+        self.embeddings = _Create(self, "embeddings", self._client.embeddings.create)
+
+    def _request(self, operation: str, model: str, kwargs: dict) -> dict:
+        if not isinstance(model, str) or not _MODEL.fullmatch(model):
+            raise ModelAccessError("Model reference is invalid")
+        if _RESERVED.intersection(kwargs) or kwargs.get("stream") or kwargs.get("background"):
+            raise ModelAccessError("Platform fields and non-blocking calls are not allowed")
+        if kwargs.get("extra_query"):
+            raise ModelAccessError("Model URL query overrides are not allowed")
+        extra = dict(kwargs.pop("extra_body", None) or {})
+        if _RESERVED.union({"model", "metadata", "stream", "background"}).intersection(extra):
+            raise ModelAccessError("extra_body cannot override the model or platform fields")
+        metadata = dict(kwargs.pop("metadata", None) or {})
+        if _RESERVED.intersection(metadata):
+            raise ModelAccessError("Application metadata cannot contain platform fields")
+        headers = dict(kwargs.pop("extra_headers", None) or {})
+        for name in headers:
+            key = name.lower()
+            if key in {
+                "authorization",
+                "proxy-authorization",
+                "host",
+                "traceparent",
+                "tracestate",
+                "x-request-id",
+                "content-type",
+                "content-length",
+            } or key.startswith(("x-ai-center-", "x-litellm-", "openai-")):
+                raise ModelAccessError("Application headers cannot override platform fields")
+        ctx = self._context
+        self._model_request_count += 1
+        metadata["spend_logs_metadata"] = {
+            "ai_center": {
+                "schema_version": 2,
+                "application_id": ctx.application_id,
+                "application_version_id": ctx.application_version_id,
+                "invocation_id": ctx.invocation_id,
+                "caller_id": ctx.caller_id,
+                "trace_id": ctx.trace_id,
+                "operation": operation,
+            }
+        }
+        extra["metadata"] = metadata
+        headers.update({"traceparent": ctx.traceparent, "x-litellm-session-id": ctx.invocation_id})
+        return {**kwargs, "model": model, "extra_body": extra, "extra_headers": headers}
+
+    @property
+    def model_activity(self) -> str:
+        """Trusted Runtime completion fact; applications cannot set this value."""
+
+        return "attempted" if self._model_request_count else "none"
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> ModelClient:
+        return self
+
+    def __exit__(self, *args):
+        self.close()

ai_center_runtime-0.2.0/src/ai_center_runtime/fastapi_integration.py

@@ -0,0 +1,69 @@
+"""FastAPI 集成：一行依赖替代手写的 Invocation 绑定/解绑仪式.
+
+``model_invocation()`` 返回一个 FastAPI 依赖：请求进入时从平台受信头读取
+Invocation 并绑定到当前上下文，响应生成完毕后自动解绑；handler 内的
+``PlatformModelClient`` 调用因此自动携带正确的 Invocation。
+
+fastapi 是可选依赖：本模块顶部不导入 fastapi，只有调用
+:func:`model_invocation` 时才需要（未安装时抛带安装指引的 RuntimeError）。
+"""
+
+from collections.abc import AsyncIterator
+
+from .relay import InvocationBinding, bind_invocation
+
+# 注意：本模块不能用 `from __future__ import annotations`——依赖函数的
+# `request: Request` 注解需要运行时真实类型，FastAPI 按函数全局命名空间
+# 解析字符串注解时拿不到闭包内的局部绑定。
+
+INVOCATION_HEADER = "x-ai-center-invocation-id"
+
+_LAZY_FASTAPI_HINT = (
+    "model_invocation() 需要 FastAPI 支持：pip install 'ai-center-runtime[fastapi]'"
+)
+
+
+def model_invocation(
+    *,
+    header: str = INVOCATION_HEADER,
+    required: bool = True,
+):
+    """FastAPI 依赖工厂：自动绑定平台 Invocation，响应后自动解绑.
+
+    用法（替代手写读 header + bind + try/finally restore）::
+
+        from ai_center_runtime import model_invocation
+
+        @app.post("/extract")
+        async def extract(
+            req: ExtractRequest,
+            _binding=Depends(model_invocation()),
+        ):
+            # 依赖已绑定：本 handler 内的 Relay 调用自动携带 Invocation
+            ...
+
+    返回裸依赖函数（配 ``Depends(...)`` 使用）。``required=True``（默认）
+    时缺头直接 422；``required=False`` 允许无 Invocation 的请求通过
+    （未绑定时 Relay 调用会在调用点抛 ``MODEL_INVOCATION_MISSING``，
+    fail-closed 语义不变）。
+    """
+
+    try:
+        from fastapi import HTTPException, Request
+    except ImportError as exc:  # pragma: no cover - 取决于环境是否安装 fastapi
+        raise RuntimeError(_LAZY_FASTAPI_HINT) from exc
+
+    async def dependency(request: Request) -> AsyncIterator[InvocationBinding]:
+        invocation_id = request.headers.get(header)
+        if not invocation_id and required:
+            raise HTTPException(
+                status_code=422,
+                detail=f"required header is missing: {header}",
+            )
+        binding = bind_invocation(invocation_id)
+        try:
+            yield binding
+        finally:
+            binding.restore()
+
+    return dependency