jdcloud-agentgrid 0.1.3__py3-none-any.whl

agentgrid/__init__.py

@@ -0,0 +1,11 @@
+"""AgentGrid Python SDK 顶层导出。
+
+根据 OpenSpec `sdk-packaging-and-entrypoint` 能力约束，v1 必须稳定支持:
+`from agentgrid import AgentGridProfile`。
+"""
+
+from .profile import AgentGridProfile
+from .session import code_session, runtime_session
+from .version import __version__
+
+__all__ = ["AgentGridProfile", "runtime_session", "code_session", "__version__"]

agentgrid/apps/__init__.py

@@ -0,0 +1,5 @@
+"""AgentGrid 应用层导出。"""
+
+from .base_app import BaseAgentGridApp
+
+__all__ = ["BaseAgentGridApp"]

agentgrid/apps/base_app.py

@@ -0,0 +1,13 @@
+"""AgentGrid 应用抽象基类。"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class BaseAgentGridApp(ABC):
+    """应用层统一运行接口。"""
+
+    @abstractmethod
+    def run(self, host: str | None = None, port: int = 8000) -> None:
+        """启动应用服务。"""

agentgrid/apps/simple_app/__init__.py

@@ -0,0 +1,5 @@
+"""AgentGrid simple app 导出。"""
+
+from .simple_app import AgentGridSimpleApp
+
+__all__ = ["AgentGridSimpleApp"]

agentgrid/apps/simple_app/simple_app.py

@@ -0,0 +1,63 @@
+"""AgentGrid simple app 实现。"""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any, Callable
+
+import uvicorn
+from starlette.applications import Starlette
+from starlette.routing import Route
+
+from agentgrid.apps.base_app import BaseAgentGridApp
+from agentgrid.apps.simple_app.simple_app_handlers import (
+    AsyncTaskHandler,
+    InvokeHandler,
+    PingHandler,
+)
+
+
+class AgentGridSimpleApp(BaseAgentGridApp, Starlette):
+    """AgentGrid simple app。"""
+
+    def __init__(self) -> None:
+        self.ping_handler = PingHandler()
+        self.invoke_handler = InvokeHandler()
+        self.async_task_handler = AsyncTaskHandler()
+
+        routes = [
+            Route("/ping", self.ping_handler.handle, methods=["GET"]),
+            Route("/health", self.ping_handler.health_check, methods=["GET"]),
+            Route("/readiness", self.ping_handler.readiness, methods=["GET"]),
+            Route("/liveness", self.ping_handler.liveness, methods=["GET"]),
+            Route("/invoke", self.invoke_handler.handle, methods=["POST"]),
+            Route("/invocations", self.invoke_handler.handle, methods=["POST"]),
+            Route(
+                "/v1/regions/{region}/runtimes/{runtime_id}:invoke",
+                self.invoke_handler.handle,
+                methods=["POST"],
+            ),
+        ]
+
+        super().__init__(routes=routes)
+
+    def entrypoint(self, func: Callable[..., Any]) -> Callable[..., Any]:
+        """注册 `/invoke` 处理函数。"""
+
+        self.invoke_handler.func = func
+        return func
+
+    def ping(self, func: Callable[..., Any]) -> Callable[..., Any]:
+        """注册 `/ping` 检查函数。"""
+
+        assert len(list(inspect.signature(func).parameters.keys())) == 0, (
+            f"Health check function `{func.__name__}` should not receive any arguments."
+        )
+        self.ping_handler.func = func
+        return func
+
+    def run(self, host: str | None = None, port: int = 8080) -> None:
+        """启动 Web 应用。"""
+
+        resolved_host = host if host else "0.0.0.0"
+        uvicorn.run(self, host=resolved_host, port=port)

agentgrid/apps/simple_app/simple_app_handlers.py

@@ -0,0 +1,252 @@
+"""AgentGrid simple app 请求处理器。"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+import logging
+import threading
+import time
+import uuid
+from abc import ABC, abstractmethod
+from typing import Any, Callable
+
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response, StreamingResponse
+
+
+logger = logging.getLogger(__name__)
+
+
+def _safe_serialize_to_json_string(value: Any) -> str:
+    """将任意对象安全序列化为 JSON 字符串。"""
+
+    try:
+        return json.dumps(value, ensure_ascii=False, default=str)
+    except TypeError:
+        return json.dumps(str(value), ensure_ascii=False)
+
+
+class BaseHandler(ABC):
+    """处理器基类。"""
+
+    def __init__(self, func: Callable[..., Any] | None = None) -> None:
+        self.func = func
+
+    @abstractmethod
+    async def handle(self, request: Request) -> Response:
+        """处理请求。"""
+
+
+class InvokeHandler(BaseHandler):
+    """`/invoke` 处理器。"""
+
+    async def handle(self, request: Request) -> Response | StreamingResponse:
+        if not self.func:
+            logger.error("Invoke handler function is not set")
+            return Response(status_code=404)
+
+        payload, headers, result = await self._process_invoke(request)
+        logger.debug(
+            "Invoke payload keys=%s headers_count=%s", payload.keys(), len(headers)
+        )
+
+        if inspect.isgenerator(result):
+            return StreamingResponse(
+                self._sync_stream_with_error_handling(result),
+                media_type="text/event-stream",
+            )
+
+        if inspect.isasyncgen(result):
+            return StreamingResponse(
+                self._stream_with_error_handling(result),
+                media_type="text/event-stream",
+            )
+
+        safe_json_string = _safe_serialize_to_json_string(result)
+        return Response(safe_json_string, media_type="application/json")
+
+    async def _process_invoke(
+        self, request: Request
+    ) -> tuple[dict[str, Any], dict[str, str], Any]:
+        """按 agentkit 兼容规则分发 entrypoint 参数。"""
+
+        if not self.func:
+            logger.error("Invoke handler function is not set")
+            return {}, {}, {"message": "Invoke handler function is not set."}
+
+        payload: dict[str, Any] = await request.json()
+        headers = dict(request.headers)
+
+        param_names = list(inspect.signature(self.func).parameters.keys())
+        num_params = len(param_names)
+
+        if num_params == 0:
+            args: tuple[Any, ...] = ()
+        elif num_params == 1:
+            if param_names[0].lower() == "request":
+                args = (request,)
+            else:
+                args = (payload,)
+        else:
+            args = (payload, headers)
+
+        if asyncio.iscoroutinefunction(self.func):
+            return payload, headers, await self.func(*args)
+        return payload, headers, self.func(*args)
+
+    def _convert_to_sse(self, obj: Any) -> bytes:
+        """将对象编码为 SSE 数据帧。"""
+
+        if isinstance(obj, str):
+            payload = obj
+        else:
+            payload = _safe_serialize_to_json_string(obj)
+        return f"data: {payload}\n\n".encode("utf-8")
+
+    def _sync_stream_with_error_handling(self, generator: Any):
+        """包装同步生成器，保证异常时输出错误事件。"""
+
+        try:
+            for value in generator:
+                yield self._convert_to_sse(value)
+        except Exception as exc:  # pragma: no cover - 通过集成用例覆盖
+            logger.exception("Error in sync streaming")
+            yield self._convert_to_sse(
+                {
+                    "error": str(exc),
+                    "error_type": type(exc).__name__,
+                    "message": "An error occurred during streaming",
+                }
+            )
+
+    async def _stream_with_error_handling(self, generator: Any):
+        """包装异步生成器，保证异常时输出错误事件。"""
+
+        try:
+            async for value in generator:
+                yield self._convert_to_sse(value)
+        except Exception as exc:  # pragma: no cover - 通过集成用例覆盖
+            logger.exception("Error in async streaming")
+            yield self._convert_to_sse(
+                {
+                    "error": str(exc),
+                    "error_type": type(exc).__name__,
+                    "message": "An error occurred during streaming",
+                }
+            )
+
+
+class PingHandler(BaseHandler):
+    """`/ping` 与健康检查处理器。"""
+
+    async def handle(self, request: Request) -> Response:
+        del request
+
+        if not self.func:
+            logger.error("Ping handler function is not set")
+            return Response(status_code=404)
+
+        if asyncio.iscoroutinefunction(self.func):
+            result = await self.func()
+        else:
+            result = self.func()
+
+        return JSONResponse(content={"status": result}, media_type="application/json")
+
+    async def health_check(self, request: Request) -> Response:
+        del request
+        return JSONResponse(
+            content={
+                "status": "healthy",
+                "timestamp": time.time(),
+                "service": "agent-service",
+            },
+            media_type="application/json",
+        )
+
+    async def readiness(self, request: Request) -> Response:
+        del request
+        return JSONResponse(
+            content={
+                "status": "success",
+                "timestamp": time.time(),
+                "service": "agent-service",
+            },
+            media_type="application/json",
+        )
+
+    async def liveness(self, request: Request) -> Response:
+        del request
+        return JSONResponse(
+            content={
+                "status": "success",
+                "timestamp": time.time(),
+                "service": "agent-service",
+            },
+            media_type="application/json",
+        )
+
+
+class AsyncTaskHandler(BaseHandler):
+    """异步任务跟踪处理器。"""
+
+    def __init__(self, func: Callable[..., Any] | None = None) -> None:
+        super().__init__(func=func)
+        self._active_tasks: dict[int, dict[str, Any]] = {}
+        self._task_counter_lock = threading.Lock()
+
+    async def handle(self, request: Request) -> Response:
+        del request
+        return Response()
+
+    def get_async_task_info(self) -> dict[str, Any]:
+        """获取当前活跃异步任务信息。"""
+
+        running_jobs: list[dict[str, Any]] = []
+        for task in self._active_tasks.values():
+            try:
+                running_jobs.append(
+                    {
+                        "name": task.get("name", "unknown"),
+                        "duration": time.time() - task.get("start_time", time.time()),
+                    }
+                )
+            except Exception as exc:  # pragma: no cover - 防御性分支
+                logger.warning("Caught exception, continuing...: %s", exc)
+                continue
+
+        return {"active_count": len(self._active_tasks), "running_jobs": running_jobs}
+
+    def add_async_task(self, name: str, metadata: dict[str, Any] | None = None) -> int:
+        """注册异步任务并返回任务 ID。"""
+
+        with self._task_counter_lock:
+            task_id = hash(str(uuid.uuid4()))
+            task_info: dict[str, Any] = {"name": name, "start_time": time.time()}
+            if metadata:
+                task_info["metadata"] = metadata
+            self._active_tasks[task_id] = task_info
+
+        logger.info("Async task started: %s (ID: %s)", name, task_id)
+        return task_id
+
+    def complete_async_task(self, task_id: int) -> bool:
+        """完成异步任务。"""
+
+        with self._task_counter_lock:
+            task_info = self._active_tasks.pop(task_id, None)
+            if not task_info:
+                logger.warning("Attempted to complete unknown task ID: %s", task_id)
+                return False
+
+            task_name = task_info.get("name", "unknown")
+            duration = time.time() - task_info.get("start_time", time.time())
+            logger.info(
+                "Async task completed: %s (ID: %s, Duration: %.2fs)",
+                task_name,
+                task_id,
+                duration,
+            )
+            return True

agentgrid/auth/__init__.py

@@ -0,0 +1,36 @@
+"""认证模块预留。
+
+v1 目标认证方式：
+- API Key
+- 京东云 AK/SK（复用底层签名能力）
+"""
+
+from .providers import ApiKeyAuthProvider, AuthProvider, JdcloudAkskAuthProvider
+from .credential_chain import (
+    DEFAULT_CREDENTIALS_PATH,
+    ENV_ACCESS_KEY,
+    ENV_SECRET_KEY,
+    InvalidCredentialSourceError,
+    resolve_aksk_credentials,
+)
+from .providers import (
+    UnsupportedAuthProviderError,
+    apply_authentication,
+    ensure_supported_profile_auth,
+    resolve_auth_provider,
+)
+
+__all__ = [
+    "AuthProvider",
+    "ApiKeyAuthProvider",
+    "JdcloudAkskAuthProvider",
+    "ENV_ACCESS_KEY",
+    "ENV_SECRET_KEY",
+    "DEFAULT_CREDENTIALS_PATH",
+    "InvalidCredentialSourceError",
+    "resolve_aksk_credentials",
+    "UnsupportedAuthProviderError",
+    "ensure_supported_profile_auth",
+    "resolve_auth_provider",
+    "apply_authentication",
+]

agentgrid/auth/credential_chain.py

@@ -0,0 +1,129 @@
+"""AK/SK 默认凭证链解析。"""
+
+from __future__ import annotations
+
+from configparser import ConfigParser
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Mapping
+import os
+
+
+ENV_ACCESS_KEY = "JDCLOUD_ACCESS_KEY"
+ENV_SECRET_KEY = "JDCLOUD_SECRET_KEY"
+DEFAULT_CREDENTIALS_PATH = Path("~/.jdcloud/credentials")
+
+
+class InvalidCredentialSourceError(ValueError):
+    """当某个凭证来源出现半配置时抛出。"""
+
+
+@dataclass(slots=True)
+class AkskCredential:
+    """解析后的 AK/SK 凭证。"""
+
+    access_key: str
+    secret_key: str
+    source: str
+
+
+def resolve_aksk_credentials(
+    *,
+    explicit_access_key: str | None,
+    explicit_secret_key: str | None,
+    environ: Mapping[str, str] | None = None,
+    credentials_path: Path | None = None,
+) -> AkskCredential | None:
+    """按优先级解析 AK/SK：显式参数 > 环境变量 > 默认文件。"""
+
+    explicit = _resolve_source(
+        source="explicit",
+        access_key=explicit_access_key,
+        secret_key=explicit_secret_key,
+        diagnostics=("显式 AK/SK 参数半配置：请同时提供 access_key 与 secret_key"),
+    )
+    if explicit is not None:
+        return explicit
+
+    env = _resolve_from_env(environ=environ)
+    if env is not None:
+        return env
+
+    return _resolve_from_credentials_file(credentials_path=credentials_path)
+
+
+def _resolve_from_env(
+    *,
+    environ: Mapping[str, str] | None,
+) -> AkskCredential | None:
+    source = environ if environ is not None else os.environ
+    access_key = source.get(ENV_ACCESS_KEY)
+    secret_key = source.get(ENV_SECRET_KEY)
+    return _resolve_source(
+        source="env",
+        access_key=access_key,
+        secret_key=secret_key,
+        diagnostics=(
+            f"环境变量半配置：请同时设置 {ENV_ACCESS_KEY} 与 {ENV_SECRET_KEY}"
+        ),
+    )
+
+
+def _resolve_from_credentials_file(
+    *,
+    credentials_path: Path | None,
+) -> AkskCredential | None:
+    path = (credentials_path or DEFAULT_CREDENTIALS_PATH).expanduser()
+    if not path.exists():
+        return None
+
+    parser = ConfigParser()
+    try:
+        parser.read(path, encoding="utf-8")
+    except Exception as exc:  # pragma: no cover
+        raise InvalidCredentialSourceError(
+            f"默认凭证文件解析失败：{path}，{exc}"
+        ) from exc
+
+    if not parser.has_section("default"):
+        return None
+
+    access_key = _normalize(parser.get("default", "access_key_id", fallback=None))
+    secret_key = _normalize(
+        parser.get("default", "secret_access_key", fallback=None)
+    )
+    return _resolve_source(
+        source="file",
+        access_key=access_key,
+        secret_key=secret_key,
+        diagnostics=(
+            "默认凭证文件半配置："
+            f"{path} 的 [default] 必须同时包含 access_key_id 与 secret_access_key"
+        ),
+    )
+
+
+def _resolve_source(
+    *,
+    source: str,
+    access_key: str | None,
+    secret_key: str | None,
+    diagnostics: str,
+) -> AkskCredential | None:
+    access = _normalize(access_key)
+    secret = _normalize(secret_key)
+
+    if access and secret:
+        return AkskCredential(access_key=access, secret_key=secret, source=source)
+    if access or secret:
+        raise InvalidCredentialSourceError(diagnostics)
+    return None
+
+
+def _normalize(value: str | None) -> str | None:
+    if value is None:
+        return None
+    normalized = value.strip()
+    if not normalized:
+        return None
+    return normalized

agentgrid/auth/providers.py

@@ -0,0 +1,122 @@
+"""认证 Provider 抽象与 v1 实现。
+
+对应 OpenSpec `auth-provider-framework`：
+- v1 仅支持 API Key 与 AK/SK 两种认证。
+- 认证注入必须走统一调用点，避免业务 client 分散拼接 header。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Optional, Protocol
+
+
+class UnsupportedAuthProviderError(ValueError):
+    """当配置了 v1 不支持的认证方式时抛出。"""
+
+
+# 历史兼容字段：早期版本允许注入 signer。
+# 真实链路接入后，AK/SK 签名由 jdcloud SDK `JDCloudClient.send()` 完成，
+# AgentGrid 不再在本层执行本地 signer。
+AkskSigner = Callable[[dict[str, str], str, str, Optional[Any]], dict[str, str]]
+
+
+class AuthProvider(Protocol):
+    """统一认证协议。
+
+    后续在请求发送前由 transport 层统一调用，避免业务 client 分散注入。
+    """
+
+    def apply(
+        self, headers: dict[str, str], *, request: Any | None = None
+    ) -> dict[str, str]:
+        """将认证信息注入请求头并返回新 headers。"""
+
+
+@dataclass(slots=True)
+class ApiKeyAuthProvider:
+    """API Key 认证实现。"""
+
+    api_key: str
+
+    def apply(
+        self, headers: dict[str, str], *, request: Any | None = None
+    ) -> dict[str, str]:
+        merged = dict(headers)
+        merged["x-api-key"] = self.api_key
+        return merged
+
+
+@dataclass(slots=True)
+class JdcloudAkskAuthProvider:
+    """京东云 AK/SK 认证 Provider。
+
+    注意：真实签名发生在 jdcloud SDK 底层 `client.send()`，
+    本 provider 仅用于表达身份类型与携带 AK/SK。
+    """
+
+    access_key: str
+    secret_key: str
+
+    def apply(
+        self, headers: dict[str, str], *, request: Any | None = None
+    ) -> dict[str, str]:
+        # AK/SK 不在本层拼接 Authorization。
+        # 真实签名由 JDCloudClient.send() 使用 Credential 自动完成。
+        _ = request
+        return dict(headers)
+
+
+def ensure_supported_profile_auth(auth: Any) -> None:
+    """校验 Profile 级认证是否在 v1 支持范围内。"""
+
+    if auth is None:
+        return
+    if isinstance(auth, (ApiKeyAuthProvider, JdcloudAkskAuthProvider)):
+        return
+    raise UnsupportedAuthProviderError(
+        "Unsupported auth provider in v1. Supported auth: ApiKeyAuthProvider, "
+        "JdcloudAkskAuthProvider"
+    )
+
+
+def resolve_auth_provider(
+    profile_auth: Any, *, api_key: str | None
+) -> AuthProvider | None:
+    """解析当前请求最终生效的认证 Provider。
+
+    规则：请求级 api_key 优先于 Profile 默认认证。
+    """
+
+    if api_key is not None:
+        return ApiKeyAuthProvider(api_key=api_key)
+
+    if profile_auth is None:
+        return None
+
+    if isinstance(profile_auth, (ApiKeyAuthProvider, JdcloudAkskAuthProvider)):
+        return profile_auth
+
+    raise UnsupportedAuthProviderError(
+        "Unsupported auth provider in v1. Supported auth: ApiKeyAuthProvider, "
+        "JdcloudAkskAuthProvider"
+    )
+
+
+def apply_authentication(
+    headers: dict[str, str],
+    *,
+    profile_auth: Any,
+    api_key: str | None,
+    request: Any | None = None,
+) -> dict[str, str]:
+    """统一认证注入调用点。
+
+    Runtime 等业务 client 必须通过该函数进行认证处理，
+    以满足 OpenSpec 对“统一抽象层注入”的约束。
+    """
+
+    provider = resolve_auth_provider(profile_auth=profile_auth, api_key=api_key)
+    if provider is None:
+        return dict(headers)
+    return provider.apply(dict(headers), request=request)