jdcloud-agentgrid 0.1.3__tar.gz

jdcloud_agentgrid-0.1.3/.gitignore

@@ -0,0 +1,46 @@
+.opencode
+
+# OS / 文件管理器
+.DS_Store
+Thumbs.db
+
+# Python 缓存与字节码
+__pycache__/
+*.py[cod]
+*$py.class
+
+# 虚拟环境
+.venv/
+venv/
+env/
+ENV/
+
+# 构建与打包产物
+build/
+dist/
+.eggs/
+*.egg-info/
+pip-wheel-metadata/
+
+# 测试、覆盖率与静态检查缓存
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+.pyre/
+.hypothesis/
+
+# Notebook
+.ipynb_checkpoints/
+
+# IDE
+.vscode/
+.idea/
+
+# 日志
+*.log
+
+
+agentgrid.yaml

jdcloud_agentgrid-0.1.3/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: jdcloud_agentgrid
+Version: 0.1.3
+Summary: AgentGrid Python SDK for JDCloud AgentGrid Runtime
+Project-URL: Homepage, https://github.com/agentgrid/agentgrid-python
+Project-URL: Repository, https://github.com/agentgrid/agentgrid-python
+Author: AgentGrid SDK Team
+Requires-Python: >=3.10
+Requires-Dist: jdcloud-sdk>=1.6.314
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: starlette>=0.37.2
+Requires-Dist: uvicorn>=0.30.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == 'dev'
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: langchain-openrouter>=0.2.1; extra == 'dev'
+Requires-Dist: langchain>=0.3.28; extra == 'dev'
+Requires-Dist: pytest>=8.2.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AgentGrid Python SDK
+
+AgentGrid Python SDK v1 提供面向 Runtime 的高层调用接口，主路径围绕以下 API：
+
+- `from agentgrid import AgentGridProfile`
+- `runtime.invoke()`
+- `runtime.create_runtime()/update_runtime()/delete_runtime()/get_runtime()/list_runtimes()`
+- `runtime_session()`
+
+## Python 版本要求
+
+- Python `>=3.10`
+
+## 安装
+
+### pip
+
+```bash
+pip install jdcloud-agentgrid
+```
+
+### uv（下游项目）
+
+```bash
+uv add jdcloud-agentgrid
+uv sync
+```
+
+## SDK 默认配置文件（agentgrid.yaml）
+
+`get_sdk_default_config()` 会自动尝试读取入口脚本同级的 `agentgrid.yaml`。
+
+- 查找规则固定为：`Path(sys.argv[0]).resolve().parent / "agentgrid.yaml"`
+- 文件不存在：忽略并回退到 SDK 内置默认配置
+- 仅识别 `basic` 节点，且字段必须是 `AgentGridConfig` 已定义字段
+
+最小示例：
+
+```yaml
+basic:
+  region: cn-north-1
+  endpoint: https://agentgrid.jdcloud-api.com
+  data_endpoint: https://agentgrid-runtime.jdcloud-api.com
+  timeout: 30
+  connect_timeout: 5
+  read_timeout: 30
+  max_retries: 2
+  user_agent_extra: demo-app/1.0
+```
+
+例如入口脚本位于 `./examples/run.py`，则配置文件应放在 `./examples/agentgrid.yaml`。
+
+
+## 最小示例（Quick Start）
+
+显式 `auth`（兼容旧用法）：
+
+```python
+from agentgrid import AgentGridProfile, runtime_session
+
+profile = AgentGridProfile(
+    region="cn-north-1",
+    data_endpoint="https://agentgrid-runtime.jdcloud-api.com",  # 可选：默认就是该地址
+)
+
+with runtime_session("cn-north-1", "your-runtime-id", profile=profile) as runtime:
+    resp = runtime.invoke(
+        {"text": "你好，AgentGrid"},
+        api_key="your-runtime-api-key",
+    )
+
+print(resp.get("output_text"))
+print(resp.get("request_id"), resp.get("trace_id"))
+```
+
+默认 AK/SK 凭证链（无需显式 `auth`）：
+
+```python
+from agentgrid import AgentGridProfile
+
+profile = AgentGridProfile(region="cn-north-1")
+```
+
+当未显式传入 `auth` 时，AK/SK 优先级固定为：
+
+1. `access_key`/`secret_key` 构造参数
+2. `JDCLOUD_ACCESS_KEY`/`JDCLOUD_SECRET_KEY`
+3. `~/.jdcloud/credentials` 的 `[default]`（`access_key_id`/`secret_access_key`）
+
+任一来源出现半配置（仅 AK 或仅 SK）会立即报错并终止降级。
+
+## 支持的认证方式（v1）
+
+- `ApiKeyAuthProvider`
+- `JdcloudAkskAuthProvider`
+
+v1 仅支持以上两种认证方式。
+
+## Runtime 与会话示例
+
+统一调用（自动 JSON/SSE 分流）：
+
+```python
+with runtime_session("cn-north-1", "rt-template-001", profile=profile) as runtime:
+    result = runtime.invoke(
+        {"text": "请总结这段文本"},
+        api_key="your-runtime-api-key",
+        metadata={"scene": "demo"},
+    )
+
+if isinstance(result, dict):
+    print(result.get("output_text"))
+else:
+    for event in result:
+        if event.type == "text_delta" and event.text:
+            print(event.text, end="", flush=True)
+```
+
+使用 `runtime_session()`：
+
+```python
+from agentgrid import runtime_session
+
+with runtime_session("cn-north-1", "chat-001", profile=profile) as runtime:
+    resp = runtime.invoke("会话内调用", api_key="your-runtime-api-key")
+    print(resp.get("session_id"))
+
+# 退出上下文时仅记录 end_session 日志，不执行显式网络清理
+```
+
+## 类型模型（v1）
+
+- `runtime.invoke()` 按响应 `Content-Type` 自动返回：
+  - JSON：`dict`
+  - SSE：可同步迭代 `StreamResponse`
+- `StreamEvent` 统一字段：`type`、`text`、`data`、`raw`
+
+## 异常与排障
+
+统一异常基类：`AgentGridError`。
+
+主要子类：
+
+- `AgentGridAuthenticationError`
+- `AgentGridAuthorizationError`
+- `AgentGridRateLimitError`
+- `AgentGridTimeoutError`
+- `AgentGridTransportError`
+- `AgentGridStreamError`
+- `AgentGridServerError`
+
+异常对象稳定暴露诊断字段：`code`、`request_id`、`retryable`。
+
+控制口与数据口边界（务必注意）：
+
+- 控制口接口（`create/update/delete/get/list`）仅支持 AK/SK，使用 API Key 会抛出 `AgentGridAuthenticationError(code="AUTHENTICATION_REQUIRED")`
+- 数据口接口（`invoke`）本期强制 API Key；优先级：请求级 `api_key` > `agentgrid.yaml` 的 `runtime.api_key`

jdcloud_agentgrid-0.1.3/README.md

@@ -0,0 +1,157 @@
+# AgentGrid Python SDK
+
+AgentGrid Python SDK v1 提供面向 Runtime 的高层调用接口，主路径围绕以下 API：
+
+- `from agentgrid import AgentGridProfile`
+- `runtime.invoke()`
+- `runtime.create_runtime()/update_runtime()/delete_runtime()/get_runtime()/list_runtimes()`
+- `runtime_session()`
+
+## Python 版本要求
+
+- Python `>=3.10`
+
+## 安装
+
+### pip
+
+```bash
+pip install jdcloud-agentgrid
+```
+
+### uv（下游项目）
+
+```bash
+uv add jdcloud-agentgrid
+uv sync
+```
+
+## SDK 默认配置文件（agentgrid.yaml）
+
+`get_sdk_default_config()` 会自动尝试读取入口脚本同级的 `agentgrid.yaml`。
+
+- 查找规则固定为：`Path(sys.argv[0]).resolve().parent / "agentgrid.yaml"`
+- 文件不存在：忽略并回退到 SDK 内置默认配置
+- 仅识别 `basic` 节点，且字段必须是 `AgentGridConfig` 已定义字段
+
+最小示例：
+
+```yaml
+basic:
+  region: cn-north-1
+  endpoint: https://agentgrid.jdcloud-api.com
+  data_endpoint: https://agentgrid-runtime.jdcloud-api.com
+  timeout: 30
+  connect_timeout: 5
+  read_timeout: 30
+  max_retries: 2
+  user_agent_extra: demo-app/1.0
+```
+
+例如入口脚本位于 `./examples/run.py`，则配置文件应放在 `./examples/agentgrid.yaml`。
+
+
+## 最小示例（Quick Start）
+
+显式 `auth`（兼容旧用法）：
+
+```python
+from agentgrid import AgentGridProfile, runtime_session
+
+profile = AgentGridProfile(
+    region="cn-north-1",
+    data_endpoint="https://agentgrid-runtime.jdcloud-api.com",  # 可选：默认就是该地址
+)
+
+with runtime_session("cn-north-1", "your-runtime-id", profile=profile) as runtime:
+    resp = runtime.invoke(
+        {"text": "你好，AgentGrid"},
+        api_key="your-runtime-api-key",
+    )
+
+print(resp.get("output_text"))
+print(resp.get("request_id"), resp.get("trace_id"))
+```
+
+默认 AK/SK 凭证链（无需显式 `auth`）：
+
+```python
+from agentgrid import AgentGridProfile
+
+profile = AgentGridProfile(region="cn-north-1")
+```
+
+当未显式传入 `auth` 时，AK/SK 优先级固定为：
+
+1. `access_key`/`secret_key` 构造参数
+2. `JDCLOUD_ACCESS_KEY`/`JDCLOUD_SECRET_KEY`
+3. `~/.jdcloud/credentials` 的 `[default]`（`access_key_id`/`secret_access_key`）
+
+任一来源出现半配置（仅 AK 或仅 SK）会立即报错并终止降级。
+
+## 支持的认证方式（v1）
+
+- `ApiKeyAuthProvider`
+- `JdcloudAkskAuthProvider`
+
+v1 仅支持以上两种认证方式。
+
+## Runtime 与会话示例
+
+统一调用（自动 JSON/SSE 分流）：
+
+```python
+with runtime_session("cn-north-1", "rt-template-001", profile=profile) as runtime:
+    result = runtime.invoke(
+        {"text": "请总结这段文本"},
+        api_key="your-runtime-api-key",
+        metadata={"scene": "demo"},
+    )
+
+if isinstance(result, dict):
+    print(result.get("output_text"))
+else:
+    for event in result:
+        if event.type == "text_delta" and event.text:
+            print(event.text, end="", flush=True)
+```
+
+使用 `runtime_session()`：
+
+```python
+from agentgrid import runtime_session
+
+with runtime_session("cn-north-1", "chat-001", profile=profile) as runtime:
+    resp = runtime.invoke("会话内调用", api_key="your-runtime-api-key")
+    print(resp.get("session_id"))
+
+# 退出上下文时仅记录 end_session 日志，不执行显式网络清理
+```
+
+## 类型模型（v1）
+
+- `runtime.invoke()` 按响应 `Content-Type` 自动返回：
+  - JSON：`dict`
+  - SSE：可同步迭代 `StreamResponse`
+- `StreamEvent` 统一字段：`type`、`text`、`data`、`raw`
+
+## 异常与排障
+
+统一异常基类：`AgentGridError`。
+
+主要子类：
+
+- `AgentGridAuthenticationError`
+- `AgentGridAuthorizationError`
+- `AgentGridRateLimitError`
+- `AgentGridTimeoutError`
+- `AgentGridTransportError`
+- `AgentGridStreamError`
+- `AgentGridServerError`
+
+异常对象稳定暴露诊断字段：`code`、`request_id`、`retryable`。
+
+控制口与数据口边界（务必注意）：
+
+- 控制口接口（`create/update/delete/get/list`）仅支持 AK/SK，使用 API Key 会抛出 `AgentGridAuthenticationError(code="AUTHENTICATION_REQUIRED")`
+- 数据口接口（`invoke`）本期强制 API Key；优先级：请求级 `api_key` > `agentgrid.yaml` 的 `runtime.api_key`

jdcloud_agentgrid-0.1.3/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling>=1.24.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "jdcloud_agentgrid"
+version = "0.1.3"
+description = "AgentGrid Python SDK for JDCloud AgentGrid Runtime"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+  { name = "AgentGrid SDK Team" },
+]
+dependencies = [
+  "jdcloud_sdk>=1.6.314",
+  "PyYAML>=6.0.2",
+  "starlette>=0.37.2",
+  "uvicorn>=0.30.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2.2",
+  "httpx>=0.27.0",
+  "langchain>=0.3.28",
+  "langchain-openrouter>=0.2.1",
+  "pytest>=8.2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/agentgrid/agentgrid-python"
+Repository = "https://github.com/agentgrid/agentgrid-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentgrid"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src",
+  "/README.md",
+  "/pyproject.toml",
+]
+
+[tool.agentgrid.versioning]
+# 版本策略：遵循语义化版本（SemVer）。
+# 只要公共 API 存在破坏性变更，必须提升主版本号。
+strategy = "semver"
+breaking_change_requires_major_bump = true
+
+[dependency-groups]
+dev = [
+    "twine>=6.2.0",
+]

jdcloud_agentgrid-0.1.3/src/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__"]

jdcloud_agentgrid-0.1.3/src/agentgrid/apps/__init__.py

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

jdcloud_agentgrid-0.1.3/src/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:
+        """启动应用服务。"""

jdcloud_agentgrid-0.1.3/src/agentgrid/apps/simple_app/__init__.py

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

jdcloud_agentgrid-0.1.3/src/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)