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

ksadk/studio/api_catalog_routes.py

@@ -89,6 +89,11 @@ def register_catalog_routes(
     async def catalog_runtimes():
         return {"items": studio.runtime_catalog(), "nextCursor": None}
 
+    @app.get("/api/v1/agent-providers")
+    async def agent_providers():
+        await studio.start()
+        return {"items": studio.agent_provider_catalog(), "nextCursor": None}
+
     @app.get("/api/v1/catalog/resources/{resource_id}")
     async def get_catalog_resource(resource_id: str):
         return studio.catalog.get(resource_id)

ksadk/studio/api_contracts.py

@@ -4,10 +4,12 @@ from __future__ import annotations
 
 from typing import Any, Literal
 
-from pydantic import Field, SecretStr
+from pydantic import Field, SecretStr, field_validator
 
+from ksadk.conversations.contracts import ConversationInput
 from ksadk.evaluation import EvaluationConfig as PublicEvaluationConfig
 from ksadk.evaluation import TargetRef
+from ksadk.scheduler.contracts import ScheduleSpec
 from ksadk.studio.contracts import (
     AgentBindings,
     AgentSpec,
@@ -48,6 +50,28 @@ class BuildRequest(ContractModel):
     evaluation_suite_refs: list[str] = Field(default_factory=list)
 
 
+class ImportRootRequest(ContractModel):
+    """一键导入根 Framework 项目（方案 §6.1）。"""
+    name: str | None = None
+    slug: str | None = None
+
+
+class PromptCompileRequest(ContractModel):
+    """PR-S2：Prompt 编译预览请求（方案 §6.2）。只读，不写 Session/Trace。"""
+    revision: int = Field(default=1, ge=1)
+    request_instructions: str = Field(default="", max_length=32768)
+    include_content: bool = False  # local debug 显式请求正文
+
+
+class ContextPreviewRequest(ContractModel):
+    """PR-S2：Context 预览请求（方案 §6.2）。复用真实 Planner，不调模型。"""
+    revision: int = Field(default=1, ge=1)
+    user_input: str = Field(default="", max_length=1_000_000)
+    request_instructions: str = Field(default="", max_length=32768)
+    simulated_history: list[MessageInput] = Field(default_factory=list)
+    include_content: bool = False
+
+
 class MessageInput(ContractModel):
     role: str = "user"
     content: str = Field(min_length=1, max_length=1_000_000)
@@ -56,7 +80,7 @@ class MessageInput(ContractModel):
 class QuickAuthoringRequest(ContractModel):
     name: str = Field(min_length=1, max_length=128)
     slug: str | None = Field(default=None, min_length=1, max_length=63)
-    runtime_type: Literal["codex", "adk", "langgraph"]
+    runtime_type: Literal["codex", "adk", "langgraph", "plugin"]
     template: Literal["blank", "research"] = "blank"
     description: str = Field(default="", max_length=1024)
     spec: AgentSpec | None = None
@@ -69,7 +93,29 @@ class AuthoringConversationMessage(ContractModel):
 
 class ConversationAuthoringRequest(ContractModel):
     messages: list[AuthoringConversationMessage] = Field(min_length=1, max_length=100)
+    # This is the single profile used to generate the Draft Patch.  It is not
+    # implicitly the deployed Agent's only model: callers may bind a separate
+    # allow-list and default below.
     model_profile_id: str = Field(min_length=3, max_length=256)
+    # Runtime is a Studio-owned deployment choice.  The authoring model only
+    # supplies semantic intent and must not choose an incompatible framework
+    # source contract on its own.
+    runtime_type: Literal["codex", "adk", "langgraph"] = "codex"
+    agent_model_profile_ids: list[str] = Field(default_factory=list, max_length=100)
+    agent_default_model_profile_id: str | None = Field(
+        default=None,
+        min_length=3,
+        max_length=256,
+    )
+    # Resource identities are selected by the Studio user, never generated by
+    # the authoring model.  The API resolves and validates their contracts
+    # before adding them to the returned Draft Patch.
+    tool_resource_ids: list[str] = Field(default_factory=list, max_length=100)
+    mcp_resource_ids: list[str] = Field(default_factory=list, max_length=100)
+    skill_resource_ids: list[str] = Field(default_factory=list, max_length=100)
+    # 可选的进度关联标识：前端生成后随请求带上，可通过
+    # GET /api/v1/authoring/conversations:status/{request_id} 轮询构建阶段。
+    request_id: str | None = Field(default=None, min_length=1, max_length=128)
 
 
 class AuthoringCommitRequest(ContractModel):
@@ -91,15 +137,107 @@ class RunRequest(ContractModel):
     sandbox: str | None = None
 
 
+class ConversationTurnRequest(ContractModel):
+    """A capability-gated local Studio turn.
+
+    Unlike the compatibility ``RunRequest`` this request deliberately contains
+    only the provider-neutral ConversationInput. The server resolves the
+    active Build's ConversationSurface and rejects undeclared intent before it
+    reaches a framework-specific runtime request.
+    """
+
+    input: ConversationInput
+    sandbox: str | None = None
+
+
+class AgentScheduleRequest(ContractModel):
+    """Browser-safe authoring input for one local ``ScheduledTask``.
+
+    Stable Agent/Build/Kernel target fields are intentionally absent.  Studio
+    resolves those from the active local Runtime binding and refuses creation
+    when it cannot prove that binding.
+    """
+
+    display_name: str = Field(min_length=1, max_length=128)
+    prompt: str = Field(min_length=1, max_length=32_768)
+    schedule: ScheduleSpec
+    enabled: bool = True
+    continuity: Literal["new_session", "continue_session"] = "new_session"
+    session_id: str | None = Field(default=None, min_length=1, max_length=256)
+
+
 class InteractionSubmitRequest(ContractModel):
     name: str = Field(min_length=1, max_length=64)
     data: dict[str, Any] = Field(default_factory=dict)
+    expected_revision: int = Field(alias="expectedRevision", ge=1)
+    idempotency_key: str = Field(alias="idempotencyKey", min_length=1, max_length=256)
 
 
-class EvaluationRequest(ContractModel):
-    suite_refs: list[str] = Field(min_length=1)
-    concurrency: int = Field(default=1, ge=1, le=4)
-    fail_fast: bool = False
+class CloudChatMessageRequest(ContractModel):
+    """One cloud turn submitted through Studio's loopback control plane.
+
+    The loopback process, never the browser, owns the AK/SK used to admit the
+    message through the cloud control plane.  ``content`` uses the same
+    OpenAI-compatible text/image/file part shape as RunAgent; execution-policy
+    fields remain bounded enums and are revalidated by Server/Runtime.
+    """
+
+    content: str | list[dict[str, Any]]
+    model: str | None = Field(default=None, min_length=1, max_length=256)
+    model_options: dict[str, Any] = Field(default_factory=dict)
+    tool_approval_mode: Literal["ask", "risk", "full"] = "risk"
+    collaboration_mode: Literal["default", "plan"] | None = None
+    goal_objective: str | None = Field(default=None, min_length=1, max_length=4096)
+
+    @field_validator("content")
+    @classmethod
+    def validate_content(cls, value):
+        if isinstance(value, str):
+            if not value.strip():
+                raise ValueError("content must not be empty")
+            if len(value) > 1_000_000:
+                raise ValueError("text content is too large")
+            return value
+        if not 1 <= len(value) <= 9:
+            raise ValueError("content must contain between 1 and 9 parts")
+        attachment_count = 0
+        for part in value:
+            kind = str(part.get("type") or "")
+            if kind == "input_text":
+                text = part.get("text")
+                if not isinstance(text, str) or not text.strip() or len(text) > 1_000_000:
+                    raise ValueError("input_text must contain bounded non-empty text")
+                continue
+            if kind == "input_image":
+                attachment_count += 1
+                url = part.get("image_url")
+                if not isinstance(url, str) or not url or len(url) > 14_000_000:
+                    raise ValueError("input_image must contain a bounded image_url")
+                continue
+            if kind == "input_file":
+                attachment_count += 1
+                filename = part.get("filename")
+                data = part.get("file_data") or part.get("file_url")
+                if not isinstance(filename, str) or not filename.strip():
+                    raise ValueError("input_file must contain a filename")
+                if not isinstance(data, str) or not data or len(data) > 14_000_000:
+                    raise ValueError("input_file must contain bounded file data")
+                continue
+            raise ValueError(f"unsupported content part: {kind or '<missing>'}")
+        if attachment_count > 8:
+            raise ValueError("a turn supports at most 8 attachments")
+        return value
+
+
+class CloudChatInteractionSubmitRequest(ContractModel):
+    """Public Interaction/v1 fields accepted by the local cloud-chat proxy."""
+
+    run_id: str = Field(min_length=1, max_length=256)
+    interaction_id: str = Field(min_length=1, max_length=256)
+    expected_revision: int = Field(ge=1)
+    action: Literal["approve", "reject", "submit", "cancel"]
+    response: dict[str, Any] = Field(default_factory=dict)
+    idempotency_key: str = Field(min_length=1, max_length=256)
 
 
 class StudioEvaluationCreate(ContractModel):
@@ -123,6 +261,10 @@ class RollbackRequest(ContractModel):
     target_build_id: str
 
 
+class CloudAgentVersionRollbackRequest(ContractModel):
+    version_id: str = Field(min_length=1, max_length=256)
+
+
 class ModelProfileCreateRequest(ContractModel):
     name: str = Field(pattern=r"^[a-z][a-z0-9._-]{1,127}$")
     display_name: str = Field(min_length=1, max_length=128)

ksadk/studio/api_memory_routes.py

@@ -0,0 +1,82 @@
+"""Memory observability and local management routes for Studio."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import FastAPI, Query
+
+from ksadk.memory.coordinator import agent_user_scope_id
+from ksadk.memory.models import MemoryDeleteRequest, MemorySearchRequest
+from ksadk.memory.providers.local_sqlite import resolve_default_memory_provider
+
+
+def register_memory_routes(app: FastAPI, studio: Any) -> None:
+    """Register PCM memory routes without expanding the central API module."""
+
+    @app.get("/api/v1/runs/{run_id}/memory-events")
+    async def get_run_memory_events(run_id: str):
+        events = studio.event_store.events(run_id)
+        items = []
+        for event in events:
+            data = event.data or {}
+            has_memory_payload = isinstance(data, dict) and (
+                "memory_event" in data
+                or any(
+                    isinstance(value, str) and value.startswith("memory.")
+                    for value in data.values()
+                )
+            )
+            if "memory" in str(event.type or "").lower() or has_memory_payload:
+                items.append({"id": event.id, "type": event.type, "data": data})
+        return {"items": items}
+
+    @app.get("/api/v1/memories")
+    async def list_memories(
+        user_id: str = Query(default="local-user", alias="userId"),
+        agent_id: str | None = Query(default=None, alias="agentId"),
+    ):
+        provider = resolve_default_memory_provider()
+        scope_id = agent_user_scope_id(agent_id=agent_id, user_id=user_id) if agent_id else user_id
+        result = provider.search(
+            MemorySearchRequest(
+                query="",
+                scopes=[("user", scope_id)],
+                memory_types=["profile", "fact", "episode"],
+                top_k=100,
+                max_tokens=10000,
+                min_score=0.0,
+            )
+        )
+        return {
+            "items": [
+                {
+                    "memory_id": record.memory_id,
+                    "scope": record.scope,
+                    "scope_id": record.scope_id,
+                    "memory_type": record.memory_type,
+                    "content": record.content[:200],
+                    "summary": record.summary,
+                    "status": record.status,
+                    "confidence": record.confidence,
+                    "created_at": record.created_at,
+                }
+                for record in result.records
+            ]
+        }
+
+    @app.delete("/api/v1/memories/{memory_id}")
+    async def delete_memory(memory_id: str):
+        provider = resolve_default_memory_provider()
+        record = provider.get(memory_id)
+        if record is None:
+            return {"deleted": False, "status": "ok"}
+        result = provider.delete(
+            MemoryDeleteRequest(
+                memory_id=memory_id,
+                scope=record.scope,
+                scope_id=record.scope_id,
+                hard=True,
+            )
+        )
+        return {"deleted": result.deleted, "status": result.status}