agentengine-sdk-python 0.8.0__py3-none-any.whl → 0.8.2__py3-none-any.whl

ksadk/studio/pagination.py

@@ -0,0 +1,182 @@
+"""Signed keyset cursors shared by Studio list endpoints.
+
+The cursor is intentionally opaque to clients.  It binds the last stable sort
+tuple to a namespace, a whitelisted sort name and the active filters so a
+cursor cannot be replayed against a different query.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import secrets
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any, TypeVar
+
+from ksadk.studio.errors import StudioError
+
+T = TypeVar("T")
+CursorScalar = str | int | float | bool | None
+
+_CURSOR_VERSION = 1
+_CURSOR_SECRET = secrets.token_bytes(32)
+_MAX_CURSOR_LENGTH = 4096
+
+
+def _invalid_cursor() -> StudioError:
+    return StudioError(
+        "PAGINATION_CURSOR_INVALID",
+        "分页游标无效或已过期",
+        status_code=422,
+        field="cursor",
+    )
+
+
+def _encode_part(value: bytes) -> str:
+    return base64.urlsafe_b64encode(value).decode("ascii").rstrip("=")
+
+
+def _decode_part(value: str) -> bytes:
+    padding = "=" * (-len(value) % 4)
+    try:
+        return base64.b64decode(value + padding, altchars=b"-_", validate=True)
+    except (ValueError, TypeError) as exc:
+        raise _invalid_cursor() from exc
+
+
+def _filter_fingerprint(filters: Mapping[str, Any]) -> str:
+    canonical = json.dumps(
+        dict(filters),
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode("utf-8")
+    return hashlib.sha256(canonical).hexdigest()[:24]
+
+
+def encode_cursor(
+    *,
+    namespace: str,
+    sort: str,
+    filters: Mapping[str, Any],
+    key: Sequence[CursorScalar],
+) -> str:
+    """Return an authenticated opaque cursor for the last emitted row."""
+
+    if not key or len(key) > 16:
+        raise ValueError("cursor key must contain between 1 and 16 values")
+    payload = {
+        "v": _CURSOR_VERSION,
+        "ns": namespace,
+        "sort": sort,
+        "filters": _filter_fingerprint(filters),
+        "key": list(key),
+    }
+    encoded = json.dumps(
+        payload,
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode("utf-8")
+    signature = hmac.new(_CURSOR_SECRET, encoded, hashlib.sha256).digest()
+    return f"{_encode_part(encoded)}.{_encode_part(signature)}"
+
+
+def decode_cursor(
+    cursor: str,
+    *,
+    namespace: str,
+    sort: str,
+    filters: Mapping[str, Any],
+) -> tuple[CursorScalar, ...]:
+    """Validate a cursor and return its stable sort tuple."""
+
+    if not cursor or len(cursor) > _MAX_CURSOR_LENGTH:
+        raise _invalid_cursor()
+    try:
+        encoded_part, signature_part = cursor.split(".", 1)
+        encoded = _decode_part(encoded_part)
+        signature = _decode_part(signature_part)
+    except ValueError as exc:
+        raise _invalid_cursor() from exc
+    expected_signature = hmac.new(_CURSOR_SECRET, encoded, hashlib.sha256).digest()
+    if not hmac.compare_digest(signature, expected_signature):
+        raise _invalid_cursor()
+    try:
+        payload = json.loads(encoded.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise _invalid_cursor() from exc
+    if not isinstance(payload, dict) or set(payload) != {
+        "v",
+        "ns",
+        "sort",
+        "filters",
+        "key",
+    }:
+        raise _invalid_cursor()
+    if (
+        payload.get("v") != _CURSOR_VERSION
+        or payload.get("ns") != namespace
+        or payload.get("sort") != sort
+        or payload.get("filters") != _filter_fingerprint(filters)
+    ):
+        raise _invalid_cursor()
+    key = payload.get("key")
+    if not isinstance(key, list) or not key or len(key) > 16:
+        raise _invalid_cursor()
+    if any(value is not None and not isinstance(value, (str, int, float, bool)) for value in key):
+        raise _invalid_cursor()
+    return tuple(key)
+
+
+def keyset_page(
+    items: Sequence[T],
+    *,
+    key: Callable[[T], Sequence[CursorScalar]],
+    reverse: bool,
+    limit: int,
+    cursor: str | None,
+    namespace: str,
+    sort: str,
+    filters: Mapping[str, Any],
+) -> dict[str, Any]:
+    """Sort and page records using a unique stable tuple.
+
+    Callers must include a unique identifier as the final key component.
+    Filters are expected to have been applied before this function is called.
+    """
+
+    page_limit = max(1, limit)
+    ordered = sorted(items, key=lambda item: tuple(key(item)), reverse=reverse)
+    remaining = ordered
+    if cursor is not None:
+        cursor_key = decode_cursor(
+            cursor,
+            namespace=namespace,
+            sort=sort,
+            filters=filters,
+        )
+        try:
+            remaining = [
+                item
+                for item in ordered
+                if (tuple(key(item)) < cursor_key if reverse else tuple(key(item)) > cursor_key)
+            ]
+        except TypeError as exc:
+            raise _invalid_cursor() from exc
+    page_items = remaining[:page_limit]
+    next_cursor = None
+    if len(remaining) > page_limit and page_items:
+        next_cursor = encode_cursor(
+            namespace=namespace,
+            sort=sort,
+            filters=filters,
+            key=key(page_items[-1]),
+        )
+    return {
+        "items": page_items,
+        "nextCursor": next_cursor,
+        "total": len(ordered),
+    }

ksadk/studio/pcm_memory.py

@@ -0,0 +1,85 @@
+"""Studio-side projection helpers for platform-owned PCM memory."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ksadk.memory.coordinator import (
+    MemoryCoordinator,
+    agent_user_scope_id,
+    build_search_request,
+    recall_to_context_item,
+)
+from ksadk.memory.events import recall_completed, recall_empty, recall_failed
+from ksadk.memory.provider_adapter import adapt_as_memory_provider
+from ksadk.memory.provider_resolver import resolve_memory_provider
+
+
+def recall_platform_memory(
+    *,
+    run_id: str,
+    session_id: str,
+    agent_id: str,
+    user_id: str,
+    user_input: str,
+    request_config: dict[str, Any],
+) -> tuple[dict[str, Any] | None, list[dict[str, Any]]]:
+    """Recall agent-scoped memory and return its auditable lifecycle event."""
+
+    if not bool(request_config.get("memory_enabled")) or not bool(
+        request_config.get("memory_recall_enabled", True)
+    ):
+        return None, []
+
+    provider_ref = str(request_config.get("provider_ref") or "local-default")
+    rollout = str(request_config.get("memory_write_rollout") or "enabled")
+    try:
+        provider = adapt_as_memory_provider(resolve_memory_provider(provider_ref))
+        result = MemoryCoordinator(provider).recall(
+            build_search_request(
+                query=user_input,
+                user_id=agent_user_scope_id(agent_id=agent_id, user_id=user_id),
+                top_k=int(request_config.get("memory_recall_top_k") or 8),
+                max_tokens=int(request_config.get("memory_recall_max_tokens") or 1600),
+                min_score=float(request_config.get("memory_recall_min_score") or 0.45),
+            )
+        )
+        context = recall_to_context_item(result)
+        if context is not None:
+            event = recall_completed(
+                run_id=run_id,
+                session_id=session_id,
+                provider=provider_ref,
+                rollout=rollout,
+                count=len(result.records),
+            )
+        elif result.status == "ok":
+            event = recall_empty(
+                run_id=run_id,
+                session_id=session_id,
+                provider=provider_ref,
+                rollout=rollout,
+            )
+        else:
+            event = recall_failed(
+                run_id=run_id,
+                session_id=session_id,
+                provider=provider_ref,
+                rollout=rollout,
+                error_code=str(result.error_code or result.status),
+                error_message="平台长期记忆召回失败",
+                retryable=result.status in {"timeout", "failed"},
+            )
+        return context, [event.to_dict()]
+    except Exception as exc:  # noqa: BLE001 - recall failure must not break a run
+        return None, [
+            recall_failed(
+                run_id=run_id,
+                session_id=session_id,
+                provider=provider_ref,
+                rollout=rollout,
+                error_code="recall_exception",
+                error_message=str(exc)[:200],
+                retryable=True,
+            ).to_dict()
+        ]

ksadk/studio/python_tool_inspection.py

@@ -0,0 +1,183 @@
+"""AST-only, inspect-before-commit staging for uploaded Python tools."""
+
+from __future__ import annotations
+
+import ast
+import hashlib
+import json
+import re
+import shutil
+from pathlib import Path, PurePath
+from typing import Any
+from uuid import uuid4
+
+from ksadk.studio.errors import StudioError
+from ksadk.studio.workspace import Workspace
+
+_MAX_SOURCE_BYTES = 1024 * 1024
+_TOKEN = re.compile(r"^pyti_[0-9a-f]{32}$")
+
+
+class PythonToolInspector:
+    """Stage Python source and expose declarations without importing it."""
+
+    def __init__(self, workspace: Workspace) -> None:
+        self.workspace = workspace
+        self.root = workspace.resolve(".agentkit/catalog/python-tool-inspections")
+        self.root.mkdir(parents=True, exist_ok=True)
+
+    def inspect(self, content: bytes, *, filename: str) -> dict[str, Any]:
+        normalized_filename = str(filename or "").strip()
+        if (
+            not normalized_filename
+            or PurePath(normalized_filename).name != normalized_filename
+            or not normalized_filename.endswith(".py")
+        ):
+            raise StudioError(
+                "PYTHON_TOOL_FILENAME_INVALID",
+                "Python Tool 必须是单个 .py 文件",
+                status_code=422,
+                field="file",
+            )
+        if not content:
+            raise StudioError(
+                "PYTHON_TOOL_EMPTY",
+                "Python Tool 文件不能为空",
+                status_code=422,
+                field="file",
+            )
+        if len(content) > _MAX_SOURCE_BYTES:
+            raise StudioError(
+                "PYTHON_TOOL_TOO_LARGE",
+                "Python Tool 源码不能超过 1 MiB",
+                status_code=413,
+                field="file",
+            )
+        try:
+            source = content.decode("utf-8")
+        except UnicodeDecodeError as exc:
+            raise StudioError(
+                "PYTHON_TOOL_ENCODING_INVALID",
+                "Python Tool 源码必须使用 UTF-8 编码",
+                status_code=422,
+                field="file",
+            ) from exc
+        try:
+            tree = ast.parse(source, filename=normalized_filename)
+        except SyntaxError as exc:
+            raise StudioError(
+                "PYTHON_TOOL_SYNTAX_INVALID",
+                f"Python 语法错误：第 {exc.lineno or 1} 行",
+                status_code=422,
+                field="file",
+                details={"line": exc.lineno, "offset": exc.offset},
+            ) from exc
+
+        callables = [
+            self._callable(node)
+            for node in tree.body
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+            and not node.name.startswith("_")
+        ]
+        if not callables:
+            raise StudioError(
+                "PYTHON_TOOL_CALLABLE_REQUIRED",
+                "文件中没有可导入的顶层公开函数",
+                status_code=422,
+                field="file",
+            )
+
+        token = f"pyti_{uuid4().hex}"
+        directory = self.root / token
+        directory.mkdir(parents=True, exist_ok=False)
+        digest = hashlib.sha256(content).hexdigest()
+        try:
+            self.workspace.atomic_write_text(directory / "tool.py", source)
+            record = {
+                "format": "agentkit.python-tool-inspection/v1",
+                "inspectionToken": token,
+                "filename": normalized_filename,
+                "sha256": digest,
+                "size": len(content),
+                "callables": callables,
+            }
+            self.workspace.atomic_write_text(
+                directory / "inspection.json",
+                json.dumps(record, ensure_ascii=False, sort_keys=True, indent=2) + "\n",
+            )
+        except BaseException:
+            shutil.rmtree(directory, ignore_errors=True)
+            raise
+        return dict(record)
+
+    def load(self, token: str) -> dict[str, Any]:
+        directory = self._directory(token)
+        record_path = directory / "inspection.json"
+        source_path = directory / "tool.py"
+        try:
+            record = json.loads(record_path.read_text(encoding="utf-8"))
+            content = source_path.read_bytes()
+        except (OSError, ValueError) as exc:
+            raise StudioError(
+                "PYTHON_TOOL_INSPECTION_NOT_FOUND",
+                "Python Tool 检查不存在或已失效",
+                status_code=404,
+            ) from exc
+        actual = hashlib.sha256(content).hexdigest()
+        if actual != str(record.get("sha256") or ""):
+            raise StudioError(
+                "PYTHON_TOOL_INSPECTION_CHANGED",
+                "Python Tool 暂存内容在确认前发生变化，请重新检查",
+                status_code=409,
+            )
+        record["sourcePath"] = self.workspace.relative(source_path)
+        return record
+
+    def consume(self, token: str) -> None:
+        shutil.rmtree(self._directory(token), ignore_errors=True)
+
+    def _directory(self, token: str) -> Path:
+        if not _TOKEN.fullmatch(str(token or "")):
+            raise StudioError(
+                "PYTHON_TOOL_INSPECTION_NOT_FOUND",
+                "Python Tool 检查不存在或已失效",
+                status_code=404,
+            )
+        directory = (self.root / token).resolve()
+        try:
+            directory.relative_to(self.root.resolve())
+        except ValueError as exc:
+            raise StudioError(
+                "PYTHON_TOOL_INSPECTION_NOT_FOUND",
+                "Python Tool 检查不存在或已失效",
+                status_code=404,
+            ) from exc
+        return directory
+
+    @staticmethod
+    def _callable(node: ast.FunctionDef | ast.AsyncFunctionDef) -> dict[str, Any]:
+        positional = [*node.args.posonlyargs, *node.args.args]
+        required_count = max(0, len(positional) - len(node.args.defaults))
+        required = [argument.arg for argument in positional[:required_count]]
+        required.extend(
+            argument.arg
+            for argument, default in zip(node.args.kwonlyargs, node.args.kw_defaults)
+            if default is None
+        )
+        parameters = [argument.arg for argument in positional]
+        if node.args.vararg is not None:
+            parameters.append(f"*{node.args.vararg.arg}")
+        parameters.extend(argument.arg for argument in node.args.kwonlyargs)
+        if node.args.kwarg is not None:
+            parameters.append(f"**{node.args.kwarg.arg}")
+        return {
+            "name": node.name,
+            "async": isinstance(node, ast.AsyncFunctionDef),
+            "description": ast.get_docstring(node) or "",
+            "parameters": parameters,
+            "required": required,
+            "line": node.lineno,
+        }
+
+
+__all__ = ["PythonToolInspector"]