jdcloud-agentgrid 0.1.3__py3-none-any.whl

agentgrid/config.py

@@ -0,0 +1,504 @@
+"""AgentGrid SDK 配置模型与默认配置管理。
+
+OpenSpec `profile-and-config-core` 要求：
+- 支持 region/endpoint/data_endpoint/timeout/max_retries/user_agent_extra 核心配置。
+- 支持 connect_timeout/read_timeout 细粒度超时。
+- 支持 SDK 默认级与 Profile 级配置合并，Profile 级覆盖默认级。
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Mapping
+from dataclasses import dataclass, field, fields, replace
+from pathlib import Path
+from urllib.parse import urlparse
+
+from jdcloud_sdk.core.config import Config as JdcloudCoreConfig
+import yaml
+
+
+DEFAULT_RUNTIME_ENDPOINT_HOST = "agentgrid.jdcloud-api.com"
+DEFAULT_RUNTIME_ENDPOINT = f"http://{DEFAULT_RUNTIME_ENDPOINT_HOST}"
+DEFAULT_RUNTIME_DATA_ENDPOINT = "https://agentgrid-cn-north-1.jdcloud.com"
+
+
+@dataclass(slots=True, frozen=True)
+class BasicConfig:
+    """agentgrid.yaml basic 节点配置。"""
+
+    region: str | None = None
+    endpoint: str | None = None
+    data_endpoint: str | None = None
+    timeout: float | None = None
+    connect_timeout: float | None = None
+    read_timeout: float | None = None
+    max_retries: int | None = None
+    user_agent_extra: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.region is not None and not self.region.strip():
+            raise ValueError("region must not be empty")
+        if self.endpoint is not None and not self.endpoint.strip():
+            raise ValueError("endpoint must not be empty")
+        if self.data_endpoint is not None and not self.data_endpoint.strip():
+            raise ValueError("data_endpoint must not be empty")
+        if self.timeout is not None and self.timeout < 0:
+            raise ValueError("timeout must be >= 0")
+        if self.connect_timeout is not None and self.connect_timeout < 0:
+            raise ValueError("connect_timeout must be >= 0")
+        if self.read_timeout is not None and self.read_timeout < 0:
+            raise ValueError("read_timeout must be >= 0")
+        if self.max_retries is not None and self.max_retries < 0:
+            raise ValueError("max_retries must be >= 0")
+
+    def to_overrides(self) -> dict[str, object]:
+        """转换为 AgentGridConfig 覆盖字段。"""
+
+        overrides: dict[str, object] = {}
+        for config_field in fields(BasicConfig):
+            value = getattr(self, config_field.name)
+            if value is not None:
+                overrides[config_field.name] = value
+        return overrides
+
+
+@dataclass(slots=True, frozen=True)
+class RuntimeConfig:
+    """agentgrid.yaml runtime 节点配置。"""
+
+    region: str | None = None
+    identifier: str | None = None
+    api_key: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.region is not None and not self.region.strip():
+            raise ValueError("runtime.region must not be empty")
+        if self.identifier is not None and not self.identifier.strip():
+            raise ValueError("runtime.identifier must not be empty")
+        if self.api_key is not None and not self.api_key.strip():
+            raise ValueError("runtime.api_key must not be empty")
+
+
+@dataclass(slots=True, frozen=True)
+class ToolConfig:
+    """agentgrid.yaml 单个工具节点配置。"""
+
+    identifier: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.identifier is not None and not self.identifier.strip():
+            raise ValueError("tool.identifier must not be empty")
+
+
+@dataclass(slots=True, frozen=True)
+class ToolsConfig:
+    """agentgrid.yaml tools 节点配置。"""
+
+    code_interpreter: ToolConfig | None = None
+    browser: ToolConfig | None = None
+
+
+@dataclass(slots=True, frozen=True)
+class Config:
+    """SDK 全局配置聚合对象。"""
+
+    basic: BasicConfig = field(default_factory=BasicConfig)
+    runtime: RuntimeConfig = field(default_factory=RuntimeConfig)
+    tools: ToolsConfig = field(default_factory=ToolsConfig)
+
+
+@dataclass(slots=True, frozen=True)
+class AgentGridConfig:
+    """AgentGrid SDK 运行时配置。"""
+
+    region: str | None = None
+    endpoint: str | None = None
+    data_endpoint: str | None = None
+    timeout: float | None = None
+    connect_timeout: float | None = None
+    read_timeout: float | None = None
+    max_retries: int = 2
+    user_agent_extra: str | None = None
+
+    def resolve_endpoint_for_jdcloud(self) -> tuple[str | None, str | None]:
+        """解析并返回 jdcloud core Config 所需 endpoint/scheme。"""
+
+        if self.endpoint is None:
+            return None, None
+
+        endpoint = self.endpoint.strip()
+        if not endpoint:
+            raise ValueError("endpoint must not be empty")
+
+        if "://" not in endpoint:
+            return endpoint, None
+
+        parsed = urlparse(endpoint)
+        if not parsed.hostname:
+            raise ValueError("endpoint must contain hostname")
+        if parsed.path and parsed.path != "/":
+            raise ValueError("endpoint must not contain path")
+        if parsed.query or parsed.fragment:
+            raise ValueError("endpoint must not contain query or fragment")
+
+        host = parsed.hostname
+        if parsed.port is not None:
+            host = f"{host}:{parsed.port}"
+        return host, parsed.scheme or None
+
+    def resolve_timeout_for_jdcloud(self) -> float | tuple[float, float] | None:
+        """解析并返回 jdcloud core Config 可用 timeout。"""
+
+        connect_timeout = self.effective_connect_timeout
+        read_timeout = self.effective_read_timeout
+        if connect_timeout is not None and read_timeout is not None:
+            if connect_timeout == read_timeout:
+                return connect_timeout
+            return (connect_timeout, read_timeout)
+        if connect_timeout is not None:
+            return connect_timeout
+        if read_timeout is not None:
+            return read_timeout
+        return None
+
+    def to_jdcloud_core_config(self) -> JdcloudCoreConfig:
+        """构建 jdcloud core `Config`，用于真实 AgentgridClient。"""
+
+        endpoint, scheme = self.resolve_endpoint_for_jdcloud()
+        if endpoint is None:
+            endpoint = DEFAULT_RUNTIME_ENDPOINT_HOST
+            scheme = "http"
+        timeout = self.resolve_timeout_for_jdcloud()
+
+        config = JdcloudCoreConfig(endpoint=endpoint)
+        if scheme is not None:
+            config.scheme = scheme
+        if timeout is not None:
+            config.timeout = timeout
+        return config
+
+    def __post_init__(self) -> None:
+        if self.endpoint is not None and not self.endpoint.strip():
+            raise ValueError("endpoint must not be empty")
+        if self.data_endpoint is not None and not self.data_endpoint.strip():
+            raise ValueError("data_endpoint must not be empty")
+        if self.timeout is not None and self.timeout < 0:
+            raise ValueError("timeout must be >= 0")
+        if self.connect_timeout is not None and self.connect_timeout < 0:
+            raise ValueError("connect_timeout must be >= 0")
+        if self.read_timeout is not None and self.read_timeout < 0:
+            raise ValueError("read_timeout must be >= 0")
+        if self.max_retries < 0:
+            raise ValueError("max_retries must be >= 0")
+
+    @property
+    def effective_connect_timeout(self) -> float | None:
+        """返回请求链路实际生效的连接超时。
+
+        协同规则：显式 connect_timeout 优先；否则回退到统一 timeout。
+        """
+
+        if self.connect_timeout is not None:
+            return self.connect_timeout
+        return self.timeout
+
+    @property
+    def effective_read_timeout(self) -> float | None:
+        """返回请求链路实际生效的读取超时。
+
+        协同规则：显式 read_timeout 优先；否则回退到统一 timeout。
+        """
+
+        if self.read_timeout is not None:
+            return self.read_timeout
+        return self.timeout
+
+    @property
+    def effective_data_endpoint(self) -> str:
+        """返回数据口实际生效 endpoint。
+
+        OpenSpec 要求控制口与数据口端点分离；当用户未显式配置 data_endpoint
+        时，数据口使用固定默认网关。
+        """
+
+        if self.data_endpoint is None:
+            return DEFAULT_RUNTIME_DATA_ENDPOINT
+        return self.data_endpoint
+
+    def merged_with(self, override: AgentGridConfig | None) -> AgentGridConfig:
+        """返回合并后的配置对象。
+
+        合并规则：override 中非 None 字段覆盖 base；max_retries 永远采用 override。
+        """
+
+        if override is None:
+            return self
+
+        return AgentGridConfig(
+            region=override.region if override.region is not None else self.region,
+            endpoint=override.endpoint
+            if override.endpoint is not None
+            else self.endpoint,
+            data_endpoint=(
+                override.data_endpoint
+                if override.data_endpoint is not None
+                else self.data_endpoint
+            ),
+            timeout=override.timeout if override.timeout is not None else self.timeout,
+            connect_timeout=(
+                override.connect_timeout
+                if override.connect_timeout is not None
+                else self.connect_timeout
+            ),
+            read_timeout=(
+                override.read_timeout
+                if override.read_timeout is not None
+                else self.read_timeout
+            ),
+            max_retries=override.max_retries,
+            user_agent_extra=(
+                override.user_agent_extra
+                if override.user_agent_extra is not None
+                else self.user_agent_extra
+            ),
+        )
+
+    def with_overrides(self, **kwargs: object) -> AgentGridConfig:
+        """使用 dataclass replace 生成覆盖后的新配置。"""
+
+        return replace(self, **kwargs)
+
+
+_BUILTIN_SDK_DEFAULT_CONFIG = AgentGridConfig(
+    endpoint=DEFAULT_RUNTIME_ENDPOINT,
+    data_endpoint=DEFAULT_RUNTIME_DATA_ENDPOINT,
+)
+
+_SDK_DEFAULT_CONFIG = _BUILTIN_SDK_DEFAULT_CONFIG
+
+
+def _resolve_agentgrid_yaml_path() -> Path | None:
+    """解析入口脚本同级 agentgrid.yaml 绝对路径。"""
+
+    if not sys.argv or not sys.argv[0]:
+        return None
+
+    script_path = Path(sys.argv[0])
+    if not script_path.is_absolute():
+        script_path = Path.cwd() / script_path
+    return script_path.resolve().parent / "agentgrid.yaml"
+
+
+def _validate_mapping_fields(
+    *,
+    agentgrid_path: Path,
+    node_name: str,
+    mapping_obj: Mapping[object, object],
+    allowed_fields: set[str],
+) -> None:
+    """校验 mapping 节点字段是否都在白名单内。"""
+
+    unknown_fields = sorted(
+        str(field_name)
+        for field_name in mapping_obj
+        if not isinstance(field_name, str) or field_name not in allowed_fields
+    )
+    if not unknown_fields:
+        return
+
+    allowed_values = ", ".join(sorted(allowed_fields))
+    unknown_values = ", ".join(unknown_fields)
+    raise ValueError(
+        f"Invalid agentgrid.yaml at '{agentgrid_path}': unknown {node_name} fields "
+        f"[{unknown_values}], allowed fields: [{allowed_values}]"
+    )
+
+
+def _parse_basic_config(*, agentgrid_path: Path, value: object) -> BasicConfig:
+    """解析 basic 配置。"""
+
+    if value is None:
+        return BasicConfig()
+    if not isinstance(value, Mapping):
+        raise ValueError(
+            f"Invalid agentgrid.yaml at '{agentgrid_path}': basic must be a mapping object"
+        )
+
+    allowed_fields = {config_field.name for config_field in fields(BasicConfig)}
+    _validate_mapping_fields(
+        agentgrid_path=agentgrid_path,
+        node_name="basic",
+        mapping_obj=value,
+        allowed_fields=allowed_fields,
+    )
+    basic_dict = {str(key): field_value for key, field_value in value.items()}
+    try:
+        return BasicConfig(**basic_dict)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(
+            f"Invalid agentgrid.yaml at '{agentgrid_path}': invalid basic config: {exc}"
+        ) from exc
+
+
+def _parse_runtime_config(*, agentgrid_path: Path, value: object) -> RuntimeConfig:
+    """解析 runtime 配置。"""
+
+    if value is None:
+        return RuntimeConfig()
+    if not isinstance(value, Mapping):
+        raise ValueError(
+            f"Invalid agentgrid.yaml at '{agentgrid_path}': runtime must be a mapping object"
+        )
+
+    allowed_fields = {config_field.name for config_field in fields(RuntimeConfig)}
+    _validate_mapping_fields(
+        agentgrid_path=agentgrid_path,
+        node_name="runtime",
+        mapping_obj=value,
+        allowed_fields=allowed_fields,
+    )
+    runtime_dict = {str(key): field_value for key, field_value in value.items()}
+    try:
+        return RuntimeConfig(**runtime_dict)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(
+            f"Invalid agentgrid.yaml at '{agentgrid_path}': invalid runtime config: {exc}"
+        ) from exc
+
+
+def _parse_tool_config(
+    *, agentgrid_path: Path, tool_name: str, value: object
+) -> ToolConfig:
+    """解析单个工具配置。"""
+
+    if not isinstance(value, Mapping):
+        raise ValueError(
+            f"Invalid agentgrid.yaml at '{agentgrid_path}': tools.{tool_name} must be a mapping object"
+        )
+
+    allowed_fields = {config_field.name for config_field in fields(ToolConfig)}
+    _validate_mapping_fields(
+        agentgrid_path=agentgrid_path,
+        node_name=f"tools.{tool_name}",
+        mapping_obj=value,
+        allowed_fields=allowed_fields,
+    )
+    tool_dict = {str(key): field_value for key, field_value in value.items()}
+    try:
+        return ToolConfig(**tool_dict)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(
+            f"Invalid agentgrid.yaml at '{agentgrid_path}': invalid tools.{tool_name} config: {exc}"
+        ) from exc
+
+
+def _parse_tools_config(*, agentgrid_path: Path, value: object) -> ToolsConfig:
+    """解析 tools 配置。"""
+
+    if value is None:
+        return ToolsConfig()
+    if not isinstance(value, Mapping):
+        raise ValueError(
+            f"Invalid agentgrid.yaml at '{agentgrid_path}': tools must be a mapping object"
+        )
+
+    allowed_fields = {config_field.name for config_field in fields(ToolsConfig)}
+    _validate_mapping_fields(
+        agentgrid_path=agentgrid_path,
+        node_name="tools",
+        mapping_obj=value,
+        allowed_fields=allowed_fields,
+    )
+
+    tools_dict: dict[str, ToolConfig | None] = {}
+    for key, field_value in value.items():
+        key_name = str(key)
+        if field_value is None:
+            tools_dict[key_name] = None
+            continue
+        tools_dict[key_name] = _parse_tool_config(
+            agentgrid_path=agentgrid_path,
+            tool_name=key_name,
+            value=field_value,
+        )
+
+    return ToolsConfig(**tools_dict)
+
+
+def load_config() -> Config:
+    """加载入口脚本同级 agentgrid.yaml 为 Config 对象。"""
+
+    agentgrid_path = _resolve_agentgrid_yaml_path()
+    if agentgrid_path is None or not agentgrid_path.exists():
+        return Config()
+
+    try:
+        with agentgrid_path.open("r", encoding="utf-8") as yaml_file:
+            raw_config = yaml.safe_load(yaml_file)
+    except OSError as exc:
+        raise ValueError(
+            f"Failed to read agentgrid.yaml at '{agentgrid_path}': {exc}"
+        ) from exc
+    except yaml.YAMLError as exc:
+        raise ValueError(
+            f"Failed to parse agentgrid.yaml at '{agentgrid_path}': {exc}"
+        ) from exc
+
+    if raw_config is None:
+        return Config()
+    if not isinstance(raw_config, Mapping):
+        raise ValueError(
+            f"Invalid agentgrid.yaml at '{agentgrid_path}': root must be a mapping object"
+        )
+
+    allowed_root_fields = {"basic", "runtime", "tools"}
+    _validate_mapping_fields(
+        agentgrid_path=agentgrid_path,
+        node_name="root",
+        mapping_obj=raw_config,
+        allowed_fields=allowed_root_fields,
+    )
+
+    return Config(
+        basic=_parse_basic_config(
+            agentgrid_path=agentgrid_path,
+            value=raw_config.get("basic"),
+        ),
+        runtime=_parse_runtime_config(
+            agentgrid_path=agentgrid_path,
+            value=raw_config.get("runtime"),
+        ),
+        tools=_parse_tools_config(
+            agentgrid_path=agentgrid_path,
+            value=raw_config.get("tools"),
+        ),
+    )
+
+
+# 模块加载时初始化一次，全局可用。
+settings = load_config()
+
+
+def get_sdk_default_config() -> AgentGridConfig:
+    """获取 SDK 默认级配置。"""
+
+    basic_overrides = settings.basic.to_overrides()
+    if not basic_overrides:
+        return _SDK_DEFAULT_CONFIG
+
+    return _SDK_DEFAULT_CONFIG.with_overrides(**basic_overrides)
+
+
+def set_sdk_default_config(config: AgentGridConfig) -> None:
+    """设置 SDK 默认级配置。"""
+
+    global _SDK_DEFAULT_CONFIG
+    _SDK_DEFAULT_CONFIG = config
+
+
+def clear_sdk_default_config() -> None:
+    """清空 SDK 默认级配置，回退到内置默认值。"""
+
+    global _SDK_DEFAULT_CONFIG
+    _SDK_DEFAULT_CONFIG = _BUILTIN_SDK_DEFAULT_CONFIG

agentgrid/errors.py

@@ -0,0 +1,145 @@
+"""AgentGrid 统一异常定义与错误映射。"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class AgentGridError(Exception):
+    """统一异常基类。"""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        request_id: str | None = None,
+        retryable: bool | None = None,
+        raw_error: Any | None = None,
+        cause: Exception | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.request_id = request_id
+        self.retryable = retryable
+        self.raw_error = raw_error
+        self.cause = cause
+
+
+class AgentGridAuthenticationError(AgentGridError):
+    """认证失败。"""
+
+
+class AgentGridAuthorizationError(AgentGridError):
+    """鉴权失败。"""
+
+
+class AgentGridRateLimitError(AgentGridError):
+    """限流错误。"""
+
+
+class AgentGridTimeoutError(AgentGridError):
+    """超时错误。"""
+
+
+class AgentGridTransportError(AgentGridError):
+    """传输错误。"""
+
+
+class AgentGridStreamError(AgentGridError):
+    """流式处理错误。"""
+
+
+class AgentGridServerError(AgentGridError):
+    """服务端错误。"""
+
+
+def map_runtime_error_to_agentgrid_error(
+    error: Any,
+    *,
+    default_message: str,
+) -> AgentGridError:
+    """将底层错误 payload 统一映射到 AgentGrid 异常分层。"""
+
+    code, message, request_id, retryable, status = _extract_error_fields(error)
+    error_cls = _resolve_error_class(code=code, status=status)
+    return error_cls(
+        message or default_message,
+        code=code,
+        request_id=request_id,
+        retryable=retryable,
+        raw_error=error,
+    )
+
+
+def _extract_error_fields(
+    error: Any,
+) -> tuple[str | None, str | None, str | None, bool | None, int | None]:
+    if not isinstance(error, dict):
+        return None, str(error), None, None, None
+
+    code = _as_optional_upper(error.get("code"))
+    message = _as_optional_str(error.get("message"))
+    request_id = _as_optional_str(error.get("request_id"))
+    retryable_value = error.get("retryable")
+    retryable = retryable_value if isinstance(retryable_value, bool) else None
+    status = _as_optional_int(error.get("status") or error.get("status_code"))
+    return code, message, request_id, retryable, status
+
+
+def _resolve_error_class(*, code: str | None, status: int | None) -> type[AgentGridError]:
+    if code in {
+        "AUTHENTICATION_FAILED",
+        "INVALID_API_KEY",
+        "UNAUTHENTICATED",
+        "INVALID_SIGNATURE",
+    }:
+        return AgentGridAuthenticationError
+    if code in {"AUTHORIZATION_FAILED", "FORBIDDEN", "PERMISSION_DENIED"}:
+        return AgentGridAuthorizationError
+    if code in {"RATE_LIMITED", "TOO_MANY_REQUESTS"}:
+        return AgentGridRateLimitError
+    if code in {"TIMEOUT", "REQUEST_TIMEOUT", "GATEWAY_TIMEOUT"}:
+        return AgentGridTimeoutError
+    if code in {"TRANSPORT_ERROR", "NETWORK_ERROR", "CONNECTION_ERROR"}:
+        return AgentGridTransportError
+    if code in {"STREAM_ERROR", "STREAM_INTERRUPTED", "STREAM_METHOD_MISSING"}:
+        return AgentGridStreamError
+
+    if status == 401:
+        return AgentGridAuthenticationError
+    if status == 403:
+        return AgentGridAuthorizationError
+    if status == 429:
+        return AgentGridRateLimitError
+    if status in {408, 504}:
+        return AgentGridTimeoutError
+    if status is not None and 500 <= status <= 599:
+        return AgentGridServerError
+    return AgentGridServerError
+
+
+def _as_optional_str(value: Any) -> str | None:
+    if value is None:
+        return None
+    return str(value)
+
+
+def _as_optional_upper(value: Any) -> str | None:
+    parsed = _as_optional_str(value)
+    if parsed is None:
+        return None
+    return parsed.upper()
+
+
+def _as_optional_int(value: Any) -> int | None:
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value
+    try:
+        return int(str(value))
+    except ValueError:
+        return None

agentgrid/extensions/__init__.py

@@ -0,0 +1,4 @@
+"""扩展点命名空间。
+
+v1 仅预留结构入口，不承诺完整产品能力。
+"""

agentgrid/extensions/observability/__init__.py

@@ -0,0 +1,52 @@
+"""可观测性扩展点预留。
+
+对应 OpenSpec `extension-points-for-tools-and-observability`：
+- 预留 `before_request`、`after_response`、`on_error` 三类 hook。
+- v1 先提供可注册与触发的最小实现，便于后续观测能力平滑接入。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+Hook = Callable[[dict[str, Any]], None]
+
+
+@dataclass(slots=True)
+class ObservabilityHooks:
+    """请求生命周期 hook 容器。"""
+
+    before_request: list[Hook] = field(default_factory=list)
+    after_response: list[Hook] = field(default_factory=list)
+    on_error: list[Hook] = field(default_factory=list)
+
+    def register_before_request(self, hook: Hook) -> None:
+        self.before_request.append(hook)
+
+    def register_after_response(self, hook: Hook) -> None:
+        self.after_response.append(hook)
+
+    def register_on_error(self, hook: Hook) -> None:
+        self.on_error.append(hook)
+
+    def emit_before_request(self, payload: dict[str, Any]) -> None:
+        self._emit(self.before_request, payload)
+
+    def emit_after_response(self, payload: dict[str, Any]) -> None:
+        self._emit(self.after_response, payload)
+
+    def emit_on_error(self, payload: dict[str, Any]) -> None:
+        self._emit(self.on_error, payload)
+
+    @staticmethod
+    def _emit(hooks: list[Hook], payload: dict[str, Any]) -> None:
+        # hooks 是观测扩展点，任何单个 hook 异常都不应破坏主业务链路。
+        for hook in hooks:
+            try:
+                hook(payload)
+            except Exception:
+                continue
+
+
+__all__ = ["ObservabilityHooks", "Hook"]