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

ksadk/studio/api_catalog_routes.py

@@ -0,0 +1,324 @@
+"""Catalog, credential and capability routes for Studio."""
+
+from __future__ import annotations
+
+from typing import Awaitable, Callable, Literal
+
+from fastapi import FastAPI, File, Query, UploadFile
+from jsonschema import Draft202012Validator  # type: ignore[import-untyped]
+from jsonschema.exceptions import SchemaError  # type: ignore[import-untyped]
+
+from ksadk.studio.api_contracts import (
+    CredentialPutRequest,
+    MCPResourceCreateRequest,
+    ModelEndpointProbeRequest,
+    ModelProfileCreateRequest,
+    PythonToolCommitRequest,
+    SecretReferenceCheckRequest,
+    SkillDiscoveryCommitRequest,
+    SkillDiscoveryRequest,
+    ToolPolicyPreviewRequest,
+    ToolResourceCreateRequest,
+    ToolSchemaValidationRequest,
+)
+from ksadk.studio.contracts import MCPServerRef
+from ksadk.studio.errors import StudioError
+from ksadk.studio.model_profile_service import probe_model_endpoint
+from ksadk.studio.service import StudioService
+
+ModelCatalogLoader = Callable[[], Awaitable[tuple[list, str]]]
+
+
+def register_catalog_routes(
+    app: FastAPI,
+    studio: StudioService,
+    *,
+    runtime_model_catalog: ModelCatalogLoader,
+) -> None:
+    """Register resource routes without expanding the main HTTP composition."""
+
+    @app.get("/api/v1/capabilities")
+    async def capabilities(kind: str | None = None, query: str = ""):
+        return {"items": studio.list_capabilities(kind=kind, query=query)}
+
+    @app.get("/api/v1/catalog/resources")
+    async def catalog_resources(
+        kind: Literal["model", "tool", "mcp", "skill"] | None = None,
+        query: str = "",
+        source: Literal["builtin", "provider", "local", "market"] | None = None,
+        status: str | None = None,
+        installed: bool | None = None,
+        limit: int = Query(default=50, ge=1, le=200),
+        cursor: str | None = None,
+        sort: Literal["default", "displayName:asc", "displayName:desc"] = "default",
+    ):
+        if kind == "model":
+            await runtime_model_catalog()
+
+        def effective_status(resource) -> str:
+            if resource.kind != "model":
+                return resource.status
+            references = list(resource.required_secret_refs or [])
+            reference = references[0] if references else resource.contract.get("credentialRef")
+            if not reference:
+                return resource.status
+            return (
+                "ready"
+                if studio.credentials.status(str(reference))["configured"]
+                else "missing-secret"
+            )
+
+        return studio.catalog.list_page(
+            kind=kind,
+            query=query,
+            source=source,
+            status=status,
+            installed=installed,
+            limit=limit,
+            cursor=cursor,
+            sort=sort,
+            status_resolver=effective_status,
+        )
+
+    @app.get("/api/v1/catalog/models")
+    async def catalog_models():
+        items, source = await runtime_model_catalog()
+        return {"items": items, "source": source, "nextCursor": None}
+
+    @app.get("/api/v1/catalog/runtimes")
+    async def catalog_runtimes():
+        return {"items": studio.runtime_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)
+
+    @app.post("/api/v1/catalog/model-profiles", status_code=201)
+    async def create_model_profile(payload: ModelProfileCreateRequest):
+        return studio.catalog.create_model_profile(
+            name=payload.name,
+            display_name=payload.display_name,
+            version=payload.version,
+            description=payload.description,
+            spec=payload.spec,
+        )
+
+    @app.post("/api/v1/catalog/mcp-servers", status_code=201)
+    async def create_mcp_resource(payload: MCPResourceCreateRequest):
+        return studio.catalog.create_mcp_server(
+            display_name=payload.display_name,
+            description=payload.description,
+            server=payload.server,
+        )
+
+    @app.post("/api/v1/catalog/mcp-servers/{resource_id}:probe")
+    async def probe_mcp_resource(
+        resource_id: str,
+        timeout_seconds: int = Query(default=10, alias="timeoutSeconds", ge=1, le=60),
+    ):
+        descriptor = studio.catalog.get(resource_id)
+        if descriptor.kind != "mcp":
+            raise StudioError(
+                "RESOURCE_KIND_INVALID",
+                "该 Resource 不是 MCP Server",
+                status_code=422,
+                details={"resourceId": resource_id},
+            )
+        server_payload = {
+            key: value for key, value in descriptor.contract.items() if key != "discoveredTools"
+        }
+        server = MCPServerRef.model_validate(server_payload)
+        try:
+            result = await studio.mcp_runtime.probe(server, timeout_seconds=timeout_seconds)
+        except StudioError as exc:
+            detail = str((exc.details or {}).get("detail") or exc.message)
+            studio.catalog.mark_probe_failed(resource_id, code=exc.code, detail=detail)
+            raise
+        return studio.catalog.save_probe(resource_id, result=result)
+
+    @app.delete("/api/v1/catalog/resources/{resource_id}", status_code=204)
+    async def delete_catalog_resource(resource_id: str):
+        descriptor = studio.catalog.get(resource_id)
+        if descriptor.kind not in {"mcp", "tool", "model", "skill"}:
+            raise StudioError(
+                "RESOURCE_KIND_INVALID",
+                "只支持删除 MCP / Tool / Model / Skill 资源",
+                status_code=422,
+                details={"kind": descriptor.kind},
+            )
+        if descriptor.kind == "model" and descriptor.source != "local":
+            raise StudioError(
+                "RESOURCE_KIND_INVALID",
+                "内置或上游发现的模型不可删除；仅支持删除手动添加的模型",
+                status_code=422,
+                details={"kind": descriptor.kind, "source": descriptor.source},
+            )
+        studio.catalog.delete_resource(resource_id)
+        return None
+
+    @app.post("/api/v1/catalog/tools", status_code=201)
+    async def create_tool_resource(payload: ToolResourceCreateRequest):
+        return studio.catalog.create_tool(
+            display_name=payload.display_name,
+            category=payload.category,
+            contract=payload.contract,
+        )
+
+    @app.post("/api/v1/catalog/python-tools:inspect")
+    async def inspect_python_tool(file: UploadFile = File(...)):
+        content = await file.read(1024 * 1024 + 1)
+        return studio.catalog.inspect_python_tool(
+            content,
+            filename=file.filename or "tool.py",
+        )
+
+    @app.post(
+        "/api/v1/catalog/python-tools/{inspection_token}:commit",
+        status_code=201,
+    )
+    async def commit_python_tool(
+        inspection_token: str,
+        payload: PythonToolCommitRequest,
+    ):
+        return studio.catalog.commit_python_tool(
+            inspection_token,
+            display_name=payload.display_name,
+            name=payload.name,
+            callable_name=payload.callable_name,
+            description=payload.description,
+        )
+
+    @app.post("/api/v1/catalog/skills:import", status_code=201)
+    async def import_skill(file: UploadFile = File(...)):
+        content = await file.read(50 * 1024 * 1024 + 1)
+        return studio.catalog.import_skill_zip(content, filename=file.filename or "skill.zip")
+
+    @app.post("/api/v1/catalog/skills:discover")
+    async def discover_skills(payload: SkillDiscoveryRequest):
+        return studio.catalog.discover_skills(scan_paths=payload.scan_paths or None)
+
+    @app.get(
+        "/api/v1/catalog/skills/discoveries/{inspection_token}/candidates/{candidate_id}/files"
+    )
+    async def preview_discovered_skill(
+        inspection_token: str,
+        candidate_id: str,
+        path: str | None = Query(default=None, max_length=1024),
+    ):
+        return studio.catalog.preview_discovered_skill(
+            inspection_token,
+            candidate_id,
+            path=path,
+        )
+
+    @app.get("/api/v1/catalog/skills/{resource_id}/files")
+    async def preview_installed_skill(
+        resource_id: str,
+        path: str | None = Query(default=None, max_length=1024),
+    ):
+        return studio.catalog.preview_installed_skill(resource_id, path=path)
+
+    @app.post(
+        "/api/v1/catalog/skills/discoveries/{inspection_token}:commit",
+        status_code=201,
+    )
+    async def commit_discovered_skill(
+        inspection_token: str,
+        payload: SkillDiscoveryCommitRequest,
+    ):
+        return studio.catalog.commit_discovered_skill(
+            inspection_token,
+            payload.candidate_id,
+            overwrite=payload.overwrite,
+        )
+
+    @app.post("/api/v1/tool-schemas:validate")
+    async def validate_tool_schema(payload: ToolSchemaValidationRequest):
+        try:
+            Draft202012Validator.check_schema(payload.schema_definition)
+        except SchemaError as exc:
+            return {
+                "valid": False,
+                "diagnostics": [
+                    {
+                        "code": "TOOL_SCHEMA_INVALID",
+                        "message": exc.message,
+                        "path": list(exc.path),
+                    }
+                ],
+            }
+        errors = sorted(
+            Draft202012Validator(payload.schema_definition).iter_errors(payload.sample),
+            key=lambda error: list(error.absolute_path),
+        )
+        return {
+            "valid": not errors,
+            "diagnostics": [
+                {
+                    "code": "TOOL_SAMPLE_INVALID",
+                    "message": error.message,
+                    "path": list(error.absolute_path),
+                }
+                for error in errors
+            ],
+        }
+
+    @app.post("/api/v1/tool-policies:preview")
+    async def preview_tool_policy(payload: ToolPolicyPreviewRequest):
+        tools, permissions = studio.catalog.policy_preview(payload.bindings)
+        return {"tools": tools, "allowedPermissions": permissions}
+
+    @app.post("/api/v1/mcp-servers:probe")
+    async def probe_mcp_server(
+        payload: MCPServerRef,
+        timeout_seconds: int = Query(default=10, alias="timeoutSeconds", ge=1, le=60),
+    ):
+        return await studio.mcp_runtime.probe(payload, timeout_seconds=timeout_seconds)
+
+    @app.post("/api/v1/secret-references:check")
+    async def check_secret_reference(payload: SecretReferenceCheckRequest):
+        status = studio.credentials.status(payload.ref)
+        return {
+            "exists": status["configured"],
+            "scheme": payload.ref.partition("://")[0],
+            "source": status["source"],
+        }
+
+    @app.get("/api/v1/credentials/{credential_name}")
+    async def get_credential_status(credential_name: str):
+        return studio.credentials.status(f"env://{credential_name}")
+
+    @app.put("/api/v1/credentials/{credential_name}")
+    async def put_credential(credential_name: str, payload: CredentialPutRequest):
+        return studio.credentials.put_session(
+            credential_name,
+            payload.value.get_secret_value(),
+        )
+
+    @app.delete("/api/v1/credentials/{credential_name}")
+    async def delete_credential(credential_name: str):
+        return studio.credentials.delete_session(credential_name)
+
+    @app.post("/api/v1/model-profiles/{resource_id}:test")
+    async def test_model_profile(resource_id: str):
+        return await studio.test_model_profile(resource_id)
+
+    @app.post("/api/v1/model-endpoints:probe")
+    async def probe_model_endpoint_route(payload: ModelEndpointProbeRequest):
+        credential: str | None = None
+        if payload.api_key is not None:
+            credential = payload.api_key.get_secret_value()
+        elif payload.credential_ref:
+            try:
+                credential = studio.credentials.resolve(payload.credential_ref)
+            except Exception:
+                credential = None  # 未配置凭证时降级为匿名探测
+        guard = getattr(studio.model_client, "network_guard", None)
+        return await probe_model_endpoint(
+            url=payload.url,
+            credential=credential,
+            network_guard=guard,
+        )
+
+
+__all__ = ["register_catalog_routes"]

ksadk/studio/api_contracts.py

@@ -0,0 +1,286 @@
+"""HTTP request contracts used by the AgentKit Studio control plane."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import Field, SecretStr, field_validator
+
+from ksadk.evaluation import EvaluationConfig as PublicEvaluationConfig
+from ksadk.evaluation import TargetRef
+from ksadk.studio.contracts import (
+    AgentBindings,
+    AgentSpec,
+    ContractModel,
+    MCPServerRef,
+    ModelSpec,
+    RuntimeRef,
+    ToolContract,
+)
+
+
+class SessionExchangeRequest(ContractModel):
+    token: str = Field(min_length=16, max_length=512)
+
+
+class WorkspaceOpenRequest(ContractModel):
+    path: str
+    create: bool = False
+
+
+class CreateAgentRequest(ContractModel):
+    id: str = Field(pattern=r"^[a-z][a-z0-9-]{2,62}$")
+    name: str = Field(min_length=1, max_length=128)
+    description: str = Field(default="", max_length=1024)
+    template: str = "blank"
+    runtime: RuntimeRef | None = None
+    spec: AgentSpec | None = None
+
+
+class ValidationRequest(ContractModel):
+    revision: int = Field(ge=1)
+    level: Literal["schema", "build", "release"] = "build"
+
+
+class BuildRequest(ContractModel):
+    revision: int = Field(ge=1)
+    run_evaluation: bool = False
+    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)
+
+
+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"]
+    template: Literal["blank", "research"] = "blank"
+    description: str = Field(default="", max_length=1024)
+    spec: AgentSpec | None = None
+
+
+class AuthoringConversationMessage(ContractModel):
+    role: Literal["user", "assistant"]
+    content: str = Field(min_length=1, max_length=32768)
+
+
+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):
+    name: str | None = Field(default=None, min_length=1, max_length=128)
+    slug: str | None = Field(default=None, min_length=1, max_length=63)
+    model_profile_id: str | None = Field(default=None, min_length=3, max_length=256)
+
+
+class ProjectInspectRequest(ContractModel):
+    path: str = Field(min_length=1, max_length=4096)
+
+
+class RunRequest(ContractModel):
+    session_id: str | None = None
+    model: str | None = Field(default=None, min_length=1, max_length=256)
+    input: MessageInput
+    environment: str = "local"
+    stream: bool = True
+    sandbox: str | None = None
+
+
+class InteractionSubmitRequest(ContractModel):
+    name: str = Field(min_length=1, max_length=64)
+    data: dict[str, Any] = Field(default_factory=dict)
+
+
+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):
+    """Request for the shared CLI/Studio evaluation executor."""
+
+    evalset_file: str = Field(min_length=1, max_length=4096)
+    target: TargetRef
+    config: PublicEvaluationConfig = Field(default_factory=PublicEvaluationConfig)
+
+
+class SecretReferenceCheckRequest(ContractModel):
+    ref: str
+
+
+class CredentialPutRequest(ContractModel):
+    value: SecretStr = Field(min_length=1, max_length=16_384)
+    persistence: Literal["session"] = "session"
+
+
+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)
+    version: str = Field(default="1.0.0", min_length=1, max_length=64)
+    description: str = Field(default="", max_length=4096)
+    spec: ModelSpec
+
+
+class ModelEndpointProbeRequest(ContractModel):
+    url: str = Field(min_length=8, max_length=1024)
+    credential_ref: str | None = Field(default=None, max_length=512)
+    api_key: SecretStr | None = None
+
+
+class MCPResourceCreateRequest(ContractModel):
+    display_name: str = Field(min_length=1, max_length=128)
+    description: str = Field(default="", max_length=4096)
+    server: MCPServerRef
+
+
+class ToolResourceCreateRequest(ContractModel):
+    display_name: str = Field(min_length=1, max_length=128)
+    category: str = Field(default="custom", max_length=64)
+    contract: ToolContract
+
+
+class PythonToolCommitRequest(ContractModel):
+    display_name: str = Field(min_length=1, max_length=128)
+    name: str = Field(pattern=r"^[A-Za-z_][A-Za-z0-9_]{0,127}$")
+    callable_name: str = Field(pattern=r"^[A-Za-z_][A-Za-z0-9_]{0,127}$")
+    description: str = Field(default="", max_length=1024)
+
+
+class ToolSchemaValidationRequest(ContractModel):
+    schema_definition: dict[str, Any] = Field(alias="schema")
+    sample: Any = None
+
+
+class ToolPolicyPreviewRequest(ContractModel):
+    bindings: AgentBindings
+
+
+class SkillDiscoveryRequest(ContractModel):
+    scan_paths: list[str] = Field(default_factory=list, max_length=20)
+
+
+class SkillDiscoveryCommitRequest(ContractModel):
+    candidate_id: str = Field(min_length=1, max_length=128)
+    overwrite: bool = False
+
+
+__all__ = [name for name in globals() if name.endswith("Request")]