agentengine-sdk-python 0.7.0__py3-none-any.whl → 0.8.1__py3-none-any.whl

ksadk/model_proxy/detect.py

@@ -0,0 +1,145 @@
+"""模型能力矩阵探测(v2.3):替代简单 responses/chat 二分。
+
+"支持 responses" 不等于 "该直通"——glm-5.1 原生 responses 丢增量 delta + 拒 namespace 工具,
+经转换层反而更好。本模块用能力矩阵描述一个 (model, base_url, credential) 的真实能力,
+供路由决策(直通 responses / 走转换层 chat / …)。
+
+探测铁律(review v1):
+- **功能性 probe 而非状态码 probe**:发最小真请求打 /v1/responses,校验返回是否为
+  合法 responses 结构(有 ``output``/``status``),不只看 HTTP 200——网关对不支持的
+  端点有时也返回 200 但内容是错误页。
+- **只在 "确凿协议否定" 时翻案**:`404/405/400 unknown endpoint` 才判 "不支持 responses";
+  超时/5xx/429/401/403 一律 "unknown",不改变判定(故障 ≠ 能力缺失)。
+- ``stream_delta_ok`` 需真发流式请求才能判定,成本高,本模块默认 None(不探),
+  由调用方按需触发或默认走转换层(转换层自己生成完整 delta)。
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+import httpx
+
+Verdict = Literal["supported", "unsupported", "unknown"]
+
+
+@dataclass
+class ModelCapabilities:
+    """一个 (model, base_url, credential_scope) 的协议能力矩阵。"""
+
+    responses_supported: bool | None = None  # None = 未知(未探/不确定)
+    stream_delta_ok: bool | None = None  # 流式增量 delta;None = 未探
+    tool_types: set[str] = field(default_factory=set)  # 支持的工具 namespace
+    preferred_protocol: str = "chat"  # "responses" | "chat":路由该走哪条
+    checked_at: float = 0.0
+    verdict: Verdict = "unknown"  # 最近一次探测结论
+
+
+def _classify_responses_error(status: int, body: str) -> Verdict:
+    """把非 200 响应分类成 supported/unsupported/unknown。
+
+    只有 "确凿协议否定" 才判 unsupported;故障类一律 unknown(不误固化)。
+    """
+    if status in (404, 405):
+        return "unsupported"
+    if status == 400:
+        low = (body or "").lower()
+        # 400 且 body 含 "unknown/not supported/endpoint" -> endpoint 不支持
+        if any(k in low for k in ("unknown", "not supported", "endpoint", "unrecognized")):
+            return "unsupported"
+        return "unknown"  # 400 但不像协议级否定(可能是请求字段问题)
+    # 401/403:鉴权/权限问题,不代表 endpoint 不存在(同 key 不同能力,见 glm-5.1 403)
+    if status in (401, 403):
+        return "unknown"
+    return "unknown"  # 5xx/429/其他:故障类
+
+
+def probe_responses_capability(
+    client: httpx.Client | httpx.AsyncClient,
+    base: str,
+    key: str,
+    model: str,
+    timeout: float = 30.0,
+):
+    """功能性 probe /v1/responses,返回能力矩阵(sync) 或 coroutine(async)。
+
+    - 200 且结构合法(output+status)→ supported,preferred_protocol=responses
+    - 200 但非 responses 结构(网关伪 200)→ unsupported,preferred_protocol=chat
+    - 404/405/400 unknown → unsupported,preferred_protocol=chat
+    - 超时/5xx/429/401/403 → unknown,preferred_protocol 保持默认 chat(保守走转换层)
+
+    按 client 类型分发:``httpx.Client`` 同步返回 ``ModelCapabilities``;
+    ``httpx.AsyncClient`` 返回 coroutine(调用方 await)。
+    """
+    if isinstance(client, httpx.AsyncClient):
+        return _probe_async(client, base, key, model, timeout)
+    if isinstance(client, httpx.Client):
+        return _probe_sync(client, base, key, model, timeout)
+    raise TypeError(f"client 必须是 httpx.Client/AsyncClient,不是 {type(client).__name__}")
+
+
+def _probe_sync(
+    client: httpx.Client, base: str, key: str, model: str, timeout: float
+) -> ModelCapabilities:
+    caps = ModelCapabilities(checked_at=time.time(), verdict="unknown")
+    url = f"{base.rstrip('/')}/responses"
+    headers = {"Authorization": f"Bearer {key}", "Content-Type": "application/json"}
+    payload = {"model": model, "input": "hi", "max_output_tokens": 1, "stream": False}
+    try:
+        r = client.post(url, json=payload, headers=headers, timeout=timeout)
+    except (httpx.TimeoutException, httpx.ConnectError, httpx.HTTPError):
+        return _finalize(caps)
+    try:
+        data = r.json()
+    except ValueError:
+        data = None
+    return _apply_response(caps, r.status_code, r.text, data)
+
+
+async def _probe_async(
+    client: httpx.AsyncClient, base: str, key: str, model: str, timeout: float
+) -> ModelCapabilities:
+    caps = ModelCapabilities(checked_at=time.time(), verdict="unknown")
+    url = f"{base.rstrip('/')}/responses"
+    headers = {"Authorization": f"Bearer {key}", "Content-Type": "application/json"}
+    payload = {"model": model, "input": "hi", "max_output_tokens": 1, "stream": False}
+    try:
+        r = await client.post(url, json=payload, headers=headers, timeout=timeout)
+    except (httpx.TimeoutException, httpx.ConnectError, httpx.HTTPError):
+        return _finalize(caps)
+    try:
+        data = r.json()
+    except ValueError:
+        data = None
+    return _apply_response(caps, r.status_code, r.text, data)
+
+
+def _apply_response(
+    caps: ModelCapabilities, status: int, text: str, data: Any
+) -> ModelCapabilities:
+    if status == 200:
+        # 功能性校验:合法 responses 结构有 output + status(不只看 200)
+        if isinstance(data, dict) and "output" in data and "status" in data:
+            caps.responses_supported = True
+            caps.verdict = "supported"
+        else:
+            # 200 但不是 responses 结构(网关伪 200 / 错误页)
+            caps.responses_supported = False
+            caps.verdict = "unsupported"
+        return _finalize(caps)
+    caps.verdict = _classify_responses_error(status, text)
+    caps.responses_supported = False if caps.verdict == "unsupported" else None
+    return _finalize(caps)
+
+
+def _finalize(caps: ModelCapabilities) -> ModelCapabilities:
+    """根据 verdict 定 preferred_protocol(保守:不确定也走转换层 chat)。"""
+    if caps.verdict == "supported" and caps.responses_supported:
+        caps.preferred_protocol = "responses"
+    else:
+        # unsupported 或 unknown 都默认 chat(走转换层):unknown 时走转换层更安全,
+        # 因为转换层对 chat 模型是确定可用的,而直连 responses 在 unknown 下有风险
+        caps.preferred_protocol = "chat"
+    return caps

ksadk/model_proxy/gate.py

@@ -0,0 +1,68 @@
+"""开关与灰度配置(v2.5):默认关闭,按需启用,一键回退直连。
+
+review v1 要求:全局默认关,支持按 agent/按模型白名单开启,故障一键回退。
+设计为纯配置判定(env/agentengine.yaml 解析后传入),不含网络/proxy 生命周期——
+后者由 v2.1(codex)/v2.2(env 框架)各自接线时调用。
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ProxyGate:
+    """协议转换层的开关/灰度判定(纯函数,不持有运行时状态)。
+
+    - ``enabled``:全局开关,默认 False。
+    - ``agent_allowlist``/``model_allowlist``:细粒度白名单;空=不按此维度放行。
+    - ``denylist``:显式拒绝(优先级最高),用于故障一键回退某 agent/模型。
+
+    判定优先级:denylist > 全局 enabled > 白名单。
+    """
+
+    enabled: bool = False
+    agent_allowlist: set[str] = field(default_factory=set)
+    model_allowlist: set[str] = field(default_factory=set)
+    denylist: set[str] = field(default_factory=set)
+
+    def is_on(self, agent: str | None = None, model: str | None = None) -> bool:
+        """是否对该 (agent, model) 启用转换层。
+
+        - denylist 命中(agent 或 model)→ False(一键回退)
+        - 全局 enabled=False → False(默认关)
+        - 全局 enabled=True → True(除非 denylist)
+        - 全局关但白名单命中(agent 或 model)→ True(灰度放行)
+        """
+        if agent and agent in self.denylist:
+            return False
+        if model and model in self.denylist:
+            return False
+        if self.enabled:
+            return True
+        if agent and agent in self.agent_allowlist:
+            return True
+        if model and model in self.model_allowlist:
+            return True
+        return False
+
+    @classmethod
+    def from_env(cls) -> "ProxyGate":
+        """从 env 读开关与白名单(逗号分隔)。
+
+        - ``KSADK_MODEL_PROXY_ENABLED=1`` 全局开
+        - ``KSADK_MODEL_PROXY_AGENTS=a,b`` agent 白名单
+        - ``KSADK_MODEL_PROXY_MODELS=glm-5.2`` model 白名单
+        - ``KSADK_MODEL_PROXY_DENY=c`` 一键回退
+        """
+        def _split(name: str) -> set[str]:
+            v = os.environ.get(name, "").strip()
+            return {x.strip() for x in v.split(",") if x.strip()} if v else set()
+
+        return cls(
+            enabled=os.environ.get("KSADK_MODEL_PROXY_ENABLED") == "1",
+            agent_allowlist=_split("KSADK_MODEL_PROXY_AGENTS"),
+            model_allowlist=_split("KSADK_MODEL_PROXY_MODELS"),
+            denylist=_split("KSADK_MODEL_PROXY_DENY"),
+        )

ksadk/model_proxy/namespace.py

@@ -0,0 +1,201 @@
+"""codex namespace 工具拍平 + 还原(responses↔chat 路径)。
+
+codex 0.142+ 用 namespace 工具声明插件/MCP 工具:
+
+    {"type":"namespace","name":"mcp__x__","tools":[{"type":"function","name":"foo",...}]}
+
+并在 input 历史里发 namespace-qualified function_call:
+
+    {"type":"function_call","name":"foo","namespace":"mcp__x__",...}
+
+chat completions 只认顶层 ``function`` 工具(chat 嵌套)和 ``function.name``,
+不认 ``namespace`` 字段。本模块把 namespace 工具**拍平**成顶层 function,
+名字用确定性的 ``<namespace>__<child>``(超长 sha256 截断,与 cc-switch 一致),
+响应侧再把 flat 名字**还原**回 ``{name, namespace}``,让 codex client 能匹配
+自己的 namespace 工具注册表。
+
+请求侧拍平 + 响应侧还原都从**同一份 request tools** 经
+:func:`flatten_namespace_tool_name` 派生名字映射,前后一致,无需跨请求状态。
+
+参照 cc-switch ``transform_codex_responses_namespace.rs``(用 Python 重写)。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+CHAT_TOOL_NAME_MAX_LEN = 64
+
+
+def flatten_namespace_tool_name(namespace: str, name: str) -> str:
+    """``<namespace>__<name>``;超长则尾部接 sha256 截断,保持在 64 字符内。
+
+    截断按字符边界,保证返回值是合法 UTF-8(不会从多字节字符中间切断)。
+    """
+    full = f"{namespace}__{name}"
+    if len(full) <= CHAT_TOOL_NAME_MAX_LEN:
+        return full
+    suffix = "__" + hashlib.sha256(full.encode("utf-8")).hexdigest()[:8]
+    prefix_len = CHAT_TOOL_NAME_MAX_LEN - len(suffix)
+    prefix = ""
+    for ch in full:
+        if len(prefix.encode("utf-8")) + len(ch.encode("utf-8")) > prefix_len:
+            break
+        prefix += ch
+    return prefix + suffix
+
+
+def _namespace_children(tool: dict) -> list[dict]:
+    for key in ("tools", "children"):
+        kids = tool.get(key)
+        if isinstance(kids, list):
+            return kids
+    return []
+
+
+def build_restore_map(tools: list[Any] | None) -> dict[str, dict[str, str]]:
+    """从 request 的 namespace 工具声明建 ``flat -> {namespace, name}`` 映射。
+
+    两个不同 child 拍平后撞名时,后者覆盖前者(与 cc-switch ``or_insert`` 不同,
+    cc-switch 用 first-wins 并对撞名报错;这里取 first-wins + 调用方撞名检测)。
+    """
+    restore: dict[str, dict[str, str]] = {}
+    if not tools:
+        return restore
+    for tool in tools:
+        if not isinstance(tool, dict):
+            continue
+        if tool.get("type") == "custom":
+            # custom 工具（如 apply_patch freeform）拍平为普通 function 转发，
+            # 响应侧据此把 function_call 还原成 custom_tool_call
+            custom_name = (tool.get("name") or "").strip()
+            if custom_name:
+                restore.setdefault(
+                    custom_name,
+                    {"custom": "true", "namespace": "", "name": custom_name},
+                )
+            continue
+        if tool.get("type") != "namespace":
+            continue
+        namespace = (tool.get("name") or "").strip()
+        if not namespace:
+            continue
+        for child in _namespace_children(tool):
+            if not isinstance(child, dict) or child.get("type") != "function":
+                continue
+            name = (child.get("name") or "").strip()
+            if not name:
+                continue
+            flat = flatten_namespace_tool_name(namespace, name)
+            restore.setdefault(flat, {"namespace": namespace, "name": name})
+    return restore
+
+
+def _rewrite_qualified_calls(value: Any, owners: dict[str, dict[str, str]]) -> bool:
+    """递归把 input 里的 namespace-qualified function_call 重写成 flat name。
+
+    ``{type:function_call, name:child, namespace:ns}`` -> ``{type:function_call, name:flat}``
+    (去掉 namespace 字段);只在 (ns, name) 与 owners 条目匹配时重写。
+    """
+    changed = False
+    if isinstance(value, list):
+        for item in value:
+            changed |= _rewrite_qualified_calls(item, owners)
+    elif isinstance(value, dict):
+        if value.get("type") == "function_call":
+            namespace = (value.get("namespace") or "").strip()
+            name = (value.get("name") or "").strip()
+            if namespace and name:
+                flat = flatten_namespace_tool_name(namespace, name)
+                entry = owners.get(flat)
+                if entry and entry["namespace"] == namespace and entry["name"] == name:
+                    value["name"] = flat
+                    value.pop("namespace", None)
+                    changed = True
+        for child in value.values():
+            changed |= _rewrite_qualified_calls(child, owners)
+    return changed
+
+
+def flatten_request_namespaces(body: dict) -> dict[str, dict[str, str]]:
+    """原地拍平 body 的 namespace 工具,返回 restore_map(供响应侧还原)。
+
+    - tools:namespace children 提升为顶层 responses function 工具(flat name),
+      原 namespace 工具移除;检测撞名(两个 child 拍平后同名)则 raise。
+    - input:namespace-qualified function_call 重写为 flat name。
+    - tool_choice:namespace-typed 丢弃(chat 不认)。
+
+    返回 ``flat -> {namespace, name}`` 映射;无 namespace 工具时返回空 dict,
+    调用方可据此跳过响应侧还原。
+    """
+    tools = body.get("tools")
+    if not isinstance(tools, list):
+        return {}
+    restore = build_restore_map(tools)
+    flat_tools: list[dict] = []
+    seen_flat: set[str] = set()
+    for tool in tools:
+        if not isinstance(tool, dict):
+            continue
+        if tool.get("type") == "namespace":
+            namespace = (tool.get("name") or "").strip()
+            for child in _namespace_children(tool):
+                if not isinstance(child, dict) or child.get("type") != "function":
+                    continue
+                name = (child.get("name") or "").strip()
+                if not name or not namespace:
+                    continue
+                flat = flatten_namespace_tool_name(namespace, name)
+                if flat in seen_flat:
+                    raise ValueError(
+                        f"namespace 拍平撞名:{flat} 来自不同 child,上游无法消歧"
+                    )
+                seen_flat.add(flat)
+                flat_tools.append({
+                    "type": "function",
+                    "name": flat,
+                    "description": child.get("description", ""),
+                    "parameters": child.get("parameters", {"type": "object", "properties": {}}),
+                    **({"strict": child["strict"]} if "strict" in child else {}),
+                })
+        else:
+            flat_tools.append(tool)
+    body["tools"] = flat_tools
+    if restore and isinstance(body.get("input"), list):
+        _rewrite_qualified_calls(body["input"], restore)
+    tc = body.get("tool_choice")
+    if isinstance(tc, dict) and tc.get("type") == "namespace":
+        body.pop("tool_choice", None)
+    return restore
+
+
+def restore_function_call(item: dict, restore_map: dict[str, dict[str, str]]) -> dict:
+    """把响应里 function_call 的 flat name 还原成 ``{name, namespace}``(原地改)。
+
+    无映射或 name 不在映射中时原样返回(普通 function 工具的 call 不受影响)。
+    """
+    if not restore_map or item.get("type") != "function_call":
+        return item
+    flat = item.get("name")
+    entry = restore_map.get(flat) if isinstance(flat, str) else None
+    if entry:
+        if entry.get("custom") == "true":
+            # function_call(JSON arguments) -> custom_tool_call(原始文本 input)
+            raw_args = item.pop("arguments", "") or ""
+            try:
+                payload = json.loads(raw_args)
+                text_input = (
+                    payload.get("input", raw_args) if isinstance(payload, dict) else raw_args
+                )
+            except Exception:
+                text_input = raw_args
+            item["type"] = "custom_tool_call"
+            item["name"] = entry["name"]
+            item["input"] = text_input
+            item.pop("namespace", None)
+            return item
+        item["name"] = entry["name"]
+        item["namespace"] = entry["namespace"]
+    return item

ksadk/model_proxy/protocol_proxy.py

@@ -0,0 +1,22 @@
+"""可独立运行的转换 proxy 入口:读 env → ProxyConfig → uvicorn。
+
+用法:
+  KSPMAS_API_KEY=xxx python -m ksadk.model_proxy.protocol_proxy   # 默认 127.0.0.1:8899
+"""
+
+import os
+
+import uvicorn
+
+from .config import ProxyConfig
+from .server import create_app
+
+
+def main():
+    config = ProxyConfig.from_env()
+    port = int(os.environ.get("PORT", "8899"))
+    uvicorn.run(create_app(config), host="127.0.0.1", port=port, log_level="warning")
+
+
+if __name__ == "__main__":
+    main()