agentengine-sdk-python 0.8.4__py3-none-any.whl → 0.8.6__py3-none-any.whl

ksadk/studio/model_content_stream.py

@@ -0,0 +1,129 @@
+"""Request-local content admission for Chat and Anthropic streams."""
+
+import copy
+from dataclasses import dataclass, field
+
+from ksadk._model_json import load_model_json
+from ksadk._model_reasoning import chat_reasoning
+from ksadk.studio.model_wire_identity import invalid_model_frame
+from ksadk.studio.model_wire_tools import AnthropicToolBlocks, _object, _text
+
+
+def _reasoning(message: dict) -> str:
+    try:
+        return chat_reasoning(message)
+    except ValueError:
+        raise invalid_model_frame()
+
+
+@dataclass
+class ChatContent:
+    text: str = ""
+    reasoning: str = ""
+    finished: bool = False
+    snapshots: set[str] = field(default_factory=set)
+
+    def accept(self, delta: dict, *messages: dict) -> tuple[str, str]:
+        before_text, before_reasoning = self.text, self.reasoning
+        additions = {"text": delta.get("content"), "reasoning": _reasoning(delta)}
+        for name, value in additions.items():
+            if value is None:
+                continue
+            _text(value)
+            if value and (self.finished or name in self.snapshots):
+                raise invalid_model_frame()
+            setattr(self, name, getattr(self, name) + value)
+        for message in messages:
+            values = {}
+            if message.get("content") is not None:
+                values["text"] = _text(message["content"])
+            if any(message.get(key) is not None for key in ("reasoning_content", "reasoning")):
+                values["reasoning"] = _reasoning(message)
+            for name, value in values.items():
+                previous = getattr(self, name)
+                if (name in self.snapshots and value != previous) or not value.startswith(previous):
+                    raise invalid_model_frame()
+                setattr(self, name, value)
+                self.snapshots.add(name)
+        return self.text[len(before_text):], self.reasoning[len(before_reasoning):]
+
+
+@dataclass
+class AnthropicContent:
+    blocks: AnthropicToolBlocks
+    values: dict[int, str] = field(default_factory=dict)
+    emitted_text: str = ""
+    emitted_reasoning: str = ""
+    finished: bool = False
+    originals: dict[int, dict] = field(default_factory=dict)
+
+    def _prefix(self, kind: str) -> str:
+        pieces = []
+        for expected, (index, block_type) in enumerate(sorted(self.blocks.block_types.items())):
+            if index != expected:
+                break
+            if block_type != kind:
+                continue
+            pieces.append(self.values.get(index, ""))
+            if index not in self.blocks.closed:
+                break
+        return "".join(pieces)
+
+    def _drain(self) -> tuple[str, str]:
+        text, reasoning = self._prefix("text"), self._prefix("thinking")
+        if (not text.startswith(self.emitted_text)
+                or not reasoning.startswith(self.emitted_reasoning)):
+            raise invalid_model_frame()
+        result = text[len(self.emitted_text):], reasoning[len(self.emitted_reasoning):]
+        self.emitted_text, self.emitted_reasoning = text, reasoning
+        return result
+
+    def accept(self, event: dict) -> tuple[str, str]:
+        kind = event["type"]
+        if self.finished and kind in {"content_block_start", "content_block_delta"}:
+            raise invalid_model_frame()
+        if kind == "content_block_start":
+            block = _object(event.get("content_block"))
+            block_type = block["type"]
+            self.originals[event["index"]] = copy.deepcopy(block)
+            if block_type in {"text", "thinking"}:
+                self.values[event["index"]] = _text(block.get(block_type))
+        elif kind == "content_block_delta":
+            delta = _object(event.get("delta"))
+            field_name = {"text_delta": "text", "thinking_delta": "thinking"}.get(delta["type"])
+            if field_name is not None:
+                # A legacy proxy may omit the block index on text/thinking
+                # deltas; slot 0 stays compatible with that omission.
+                index = event["index"] if "index" in event else 0
+                self.values[index] = self.values.get(index, "") + _text(delta.get(field_name))
+            if delta["type"] == "signature_delta":
+                index = event["index"] if "index" in event else 0
+                original = self.originals.setdefault(index, {"type": "thinking"})
+                original["signature"] = original.get("signature", "") + _text(delta["signature"])
+        return self._drain()
+
+    def finish(self) -> tuple[str, str]:
+        self.blocks.finish()
+        indexes = sorted(self.blocks.block_types)
+        if any(index != expected for expected, index in enumerate(indexes)):
+            raise invalid_model_frame()
+        return self._drain()
+
+    def replay_content(self) -> tuple[dict, ...] | None:
+        self.finish()
+        values = []
+        for index, kind in sorted(self.blocks.block_types.items()):
+            block = copy.deepcopy(self.originals.get(index, {"type": kind}))
+            if kind in {"text", "thinking"}:
+                block[kind] = self.values.get(index, "")
+            elif kind == "tool_use":
+                try:
+                    block["input"] = load_model_json(self.blocks.calls[index].arguments or "{}")
+                except (ValueError, TypeError):
+                    # Invalid JSON has no complete content to replay. Retain
+                    # the tool diagnostic without fabricating original input.
+                    return None
+            values.append(block)
+        # Transport keeps opaque provider fields; the declared Native replay
+        # contract validates signed content before authorizing any tool batch.
+        return tuple(values)

ksadk/studio/model_credentials.py

@@ -0,0 +1,196 @@
+"""Workspace and session credential resolution for Studio model transports."""
+
+from __future__ import annotations
+
+import os
+from threading import RLock
+from typing import Any
+
+from ksadk.studio.errors import StudioError
+
+
+class CredentialResolver:
+    """Resolve Secret references through the shared workspace configuration.
+
+    Workspace credentials use ``.agentkit/config.yaml`` with explicit imports
+    and legacy migration. Standalone instances retain process/session behavior.
+    """
+
+    _FALLBACK_PAIRS: tuple[tuple[str, str], ...] = (
+        ("AGENTKIT_MODEL_API_KEY", "OPENAI_API_KEY"),
+        ("OPENAI_API_KEY", "AGENTKIT_MODEL_API_KEY"),
+    )
+
+    def __init__(self, workspace: Any = None, *, configuration: Any = None) -> None:
+        self._session_values: dict[str, bytearray] = {}
+        self._lock = RLock()
+        self._workspace = workspace
+        from ksadk.studio.configuration import WorkspaceConfiguration
+
+        self.configuration = configuration or (
+            WorkspaceConfiguration(workspace) if workspace is not None else None
+        )
+        self._persisted: dict[str, str] | None = None
+
+    def _load_persisted(self) -> dict[str, str]:
+        return self.configuration.secrets() if self.configuration is not None else {}
+
+    @staticmethod
+    def _validate_name(name: str) -> str:
+        allowed = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_"
+        if not name or any(char not in allowed for char in name):
+            raise StudioError(
+                "SECRET_REFERENCE_INVALID",
+                "环境变量 Secret 引用格式无效",
+                status_code=422,
+                field="credentialName",
+            )
+        return name
+
+    @classmethod
+    def _environment_name(cls, reference: str) -> str:
+        if not reference.startswith("env://"):
+            raise StudioError(
+                "SECRET_BACKEND_UNAVAILABLE",
+                "当前本地 Runtime 仅支持 env:// Secret 引用",
+                status_code=501,
+                details={"scheme": reference.partition("://")[0]},
+            )
+        return cls._validate_name(reference.removeprefix("env://"))
+
+    @staticmethod
+    def _zero(value: bytearray | None) -> None:
+        if value is not None:
+            value[:] = b"\x00" * len(value)
+
+    def put_session(self, name: str, value: str) -> dict[str, str | bool]:
+        name = self._validate_name(name)
+        if (
+            not value
+            or len(value) > 16_384
+            or value != value.strip()
+            or any(ord(char) < 32 or ord(char) == 127 for char in value)
+        ):
+            raise StudioError(
+                "SECRET_VALUE_INVALID",
+                "凭证不能为空、包含控制字符或超过 16 KiB",
+                status_code=422,
+                field="value",
+            )
+        encoded = bytearray(value.encode("utf-8"))
+        with self._lock:
+            previous = self._session_values.get(name)
+            self._session_values[name] = encoded
+            self._zero(previous)
+            if self.configuration is not None:
+                self.configuration.put_secret(name, value)
+        return self.status(f"env://{name}")
+
+    def delete_session(self, name: str) -> dict[str, str | bool]:
+        name = self._validate_name(name)
+        with self._lock:
+            previous = self._session_values.pop(name, None)
+            self._zero(previous)
+            if self.configuration is not None:
+                self.configuration.put_secret(name, None)
+        return self.status(f"env://{name}")
+
+    def clear_session(self) -> None:
+        with self._lock:
+            values = list(self._session_values.values())
+            self._session_values.clear()
+            for value in values:
+                self._zero(value)
+
+    def _fallback_name(self, name: str) -> str | None:
+        for primary, alternate in self._FALLBACK_PAIRS:
+            if name == primary and alternate != primary:
+                return alternate
+        return None
+
+    def _resolve_source(self, name: str) -> tuple[bool, str]:
+        """Return (configured, source) considering session, persisted file, env, and fallback."""
+        fallback = self._fallback_name(name)
+        if self.configuration is not None:
+            value, source = self.configuration.resolve_candidates(
+                [name, *([fallback] if fallback else [])]
+            )
+            with self._lock:
+                # put_session() keeps the session overlay and the persisted copy in
+                # sync; if the persisted copy vanished (deleted via another resolver
+                # instance) the session entry is stale and must not shadow it.
+                if value and name in self._session_values:
+                    return True, "session"
+                if value and fallback and fallback in self._session_values:
+                    return True, "session-alias"
+            return bool(value), source
+        with self._lock:
+            if name in self._session_values:
+                return True, "session"
+            if fallback and fallback in self._session_values:
+                return True, "session-alias"
+        persisted = self._load_persisted()
+        if name in persisted:
+            return True, "workspace"
+        if fallback and fallback in persisted:
+            return True, "workspace-alias"
+        if os.environ.get(name):
+            return True, "environment"
+        if fallback and os.environ.get(fallback):
+            return True, "fallback"
+        return False, "missing"
+
+    def _session_value(self, name: str) -> str | None:
+        with self._lock:
+            value = self._session_values.get(name)
+            return value.decode("utf-8") if value is not None else None
+
+    def status(self, reference: str) -> dict[str, str | bool]:
+        name = self._environment_name(reference)
+        configured, source = self._resolve_source(name)
+        return {
+            "reference": reference,
+            "name": name,
+            "configured": configured,
+            "source": source,
+            "persistence": source,
+        }
+
+    def resolve(self, reference: str, *, allow_aliases: bool = True) -> str:
+        name = self._environment_name(reference)
+        fallback = self._fallback_name(name) if allow_aliases else None
+        aliases = [name, *([fallback] if fallback else [])]
+        if self.configuration is not None:
+            value, _source = self.configuration.resolve_candidates(aliases)
+            if value:
+                return value
+            raise StudioError(
+                "SECRET_NOT_FOUND",
+                "凭证尚未配置，请在设置中填写",
+                status_code=422,
+                details={"reference": reference},
+            )
+        for candidate in aliases:
+            value = self._session_value(candidate)
+            if value is not None:
+                return value
+        persisted = self._load_persisted()
+        for candidate in aliases:
+            if candidate in persisted:
+                return persisted[candidate]
+        for candidate in aliases:
+            value = os.environ.get(candidate)
+            if value:
+                return value
+        raise StudioError(
+            "SECRET_NOT_FOUND",
+            "模型凭证尚未配置",
+            status_code=422,
+            details={"reference": reference},
+        )
+
+    def exists(self, reference: str) -> bool:
+        try:
+            return bool(self.status(reference)["configured"])
+        except StudioError:
+            return False

ksadk/studio/model_profile_service.py

@@ -9,9 +9,11 @@ from urllib.parse import urlparse
 
 import httpx
 
-from ksadk.studio.contracts import ModelSpec, NetworkPolicy
+from ksadk.studio.contracts import ANTHROPIC_VERSION, ModelSpec, NetworkPolicy
 from ksadk.studio.errors import StudioError
 
+_ANTHROPIC_VERSION = ANTHROPIC_VERSION
+
 
 async def test_model_profile_connection(
     *,
@@ -65,7 +67,8 @@ def _probe_candidates(raw_url: str) -> tuple[str, list[tuple[str, str]]]:
     支持三种输入形态：
     - https://host/v1/chat/completions → 直接候选
     - https://host/v1/responses → 直接候选
-    - https://host 或 https://host/v1 → 推导 chat / responses 候选
+    - https://host/v1/messages → 直接候选（Anthropic Messages wire）
+    - https://host 或 https://host/v1 → 推导 chat / responses / anthropic 候选
     """
     url = raw_url.strip().rstrip("/")
     if url.endswith("/chat/completions"):
@@ -74,13 +77,22 @@ def _probe_candidates(raw_url: str) -> tuple[str, list[tuple[str, str]]]:
     if url.endswith("/responses"):
         base = url[: -len("/responses")]
         return base, [("responses", url)]
+    if url.endswith("/messages"):
+        base = url[: -len("/messages")]
+        return base, [("anthropic", url)]
     if url.endswith("/v1"):
-        return url, [("chat", f"{url}/chat/completions"), ("responses", f"{url}/responses")]
+        return url, [
+            ("chat", f"{url}/chat/completions"),
+            ("responses", f"{url}/responses"),
+            ("anthropic", f"{url}/messages"),
+        ]
     return url, [
         ("chat", f"{url}/v1/chat/completions"),
         ("responses", f"{url}/v1/responses"),
+        ("anthropic", f"{url}/v1/messages"),
         ("chat", f"{url}/chat/completions"),
         ("responses", f"{url}/responses"),
+        ("anthropic", f"{url}/messages"),
     ]
 
 
@@ -96,6 +108,31 @@ def _classify_probe(status_code: int) -> str:
     return "error"
 
 
+def _recommended_probe(attempts: list[dict[str, Any]]) -> dict[str, Any] | None:
+    """Choose the profile protocol from probe results deterministically.
+
+    Responses is preferred for a generic URL when both endpoints are usable;
+    an explicitly supplied endpoint still produces a single eligible result.
+    """
+    protocol_priority = {"responses": 0, "chat": 1, "anthropic": 2}
+    for wanted in ("ok", "auth_required", "recognized"):
+        eligible = [a for a in attempts if a.get("status") == wanted]
+        hit = min(
+            eligible,
+            key=lambda attempt: protocol_priority.get(str(attempt.get("protocol")), 99),
+            default=None,
+        )
+        if hit is not None:
+            protocol = str(hit["protocol"])
+            return {
+                "protocol": protocol,
+                "wireApi": protocol if protocol in {"responses", "anthropic"} else "chat",
+                "endpointUrl": hit["endpointUrl"],
+                "status": hit["status"],
+            }
+    return None
+
+
 async def probe_model_endpoint(
     *,
     url: str,
@@ -103,7 +140,7 @@ async def probe_model_endpoint(
     network_guard: Any = None,
     timeout_seconds: float = 8.0,
 ) -> dict[str, Any]:
-    """智能探测模型端点：识别 chat / responses 协议、可用模型清单并给出推荐配置。"""
+    """智能探测模型端点：识别 chat / responses / anthropic 协议、可用模型清单并给出推荐配置。"""
     base, candidates = _probe_candidates(url)
     host = (urlparse(base).hostname or "").lower().rstrip(".")
     headers = {"Content-Type": "application/json"}
@@ -125,19 +162,28 @@ async def probe_model_endpoint(
                     allow_private_network=False,
                 ),
             )
-        payload: dict[str, Any] = (
-            {
+        request_headers = dict(headers)
+        payload: dict[str, Any]
+        if protocol == "anthropic":
+            request_headers["x-api-key"] = request_headers.pop("Authorization", "").removeprefix("Bearer ")
+            request_headers["anthropic-version"] = _ANTHROPIC_VERSION
+            payload = {
+                "model": probe_model,
+                "messages": [{"role": "user", "content": "ping"}],
+                "max_tokens": 16,
+            }
+        elif protocol == "chat":
+            payload = {
                 "model": probe_model,
                 "messages": [{"role": "user", "content": "ping"}],
                 "max_tokens": 1,
                 "stream": False,
             }
-            if protocol == "chat"
-            else {"model": probe_model, "input": "ping", "max_output_tokens": 16}
-        )
+        else:
+            payload = {"model": probe_model, "input": "ping", "max_output_tokens": 16}
         started = time.monotonic()
         try:
-            response = await client.post(endpoint, headers=headers, json=payload)
+            response = await client.post(endpoint, headers=request_headers, json=payload)
         except (httpx.TimeoutException, httpx.TransportError) as exc:
             return {
                 "protocol": protocol,
@@ -159,26 +205,39 @@ async def probe_model_endpoint(
             if not base.endswith("/v1")
             else (f"{base}/models",)
         )
+        # Anthropic Messages wire 用 x-api-key 鉴权，模型清单也用它重试一次；
+        # OpenAI 兼容网关大多同时接受 Bearer，因此 Bearer 优先。
+        auth_attempts = [headers]
+        if credential:
+            anthropic_headers = {
+                key: value for key, value in headers.items() if key != "Authorization"
+            }
+            anthropic_headers["x-api-key"] = credential
+            anthropic_headers["anthropic-version"] = _ANTHROPIC_VERSION
+            auth_attempts.append(anthropic_headers)
         for models_url in models_urls:
-            try:
-                response = await client.get(models_url, headers=headers)
-            except (httpx.TimeoutException, httpx.TransportError):
-                continue
-            if response.status_code != 200:
-                continue
-            try:
-                data = response.json()
-            except ValueError:
-                continue
-            items = data.get("data") or data.get("models") or []
-            names = [
-                str(item.get("id") or item.get("name") or "")
-                for item in items
-                if isinstance(item, dict)
-            ]
-            names = [name for name in names if name]
-            if names:
-                return sorted(set(names))[:100]
+            for attempt_headers in auth_attempts:
+                try:
+                    response = await client.get(models_url, headers=attempt_headers)
+                except (httpx.TimeoutException, httpx.TransportError):
+                    break
+                if response.status_code != 200:
+                    if response.status_code in {401, 403}:
+                        continue
+                    break
+                try:
+                    data = response.json()
+                except ValueError:
+                    continue
+                items = data.get("data") or data.get("models") or []
+                names = [
+                    str(item.get("id") or item.get("name") or "")
+                    for item in items
+                    if isinstance(item, dict)
+                ]
+                names = [name for name in names if name]
+                if names:
+                    return sorted(set(names))[:100]
         return []
 
     timeout = httpx.Timeout(timeout_seconds, connect=min(5.0, timeout_seconds))
@@ -190,17 +249,7 @@ async def probe_model_endpoint(
             *(_post(client, protocol, endpoint, probe_model) for protocol, endpoint in candidates)
         )
 
-    recommended: dict[str, Any] | None = None
-    for wanted in ("ok", "auth_required", "recognized"):
-        hit = next((a for a in attempts if a["status"] == wanted), None)
-        if hit is not None:
-            recommended = {
-                "protocol": hit["protocol"],
-                "wireApi": "responses" if hit["protocol"] == "responses" else "chat",
-                "endpointUrl": hit["endpointUrl"],
-                "status": hit["status"],
-            }
-            break
+    recommended = _recommended_probe(attempts)
 
     return {
         "input": url,