agent-builder-gateway-sdk 0.7.1__py3-none-any.whl

gateway_sdk/exceptions.py

@@ -0,0 +1,87 @@
+"""异常定义"""
+
+from typing import Any, Dict, Optional
+
+
+class GatewayError(Exception):
+    """Gateway SDK 基础异常"""
+
+    def __init__(self, message: str, details: Optional[Dict[str, Any]] = None):
+        self.message = message
+        self.details = details or {}
+        super().__init__(message)
+
+
+class AuthenticationError(GatewayError):
+    """认证失败"""
+
+    pass
+
+
+class PrefabNotFoundError(GatewayError):
+    """预制件不存在"""
+
+    def __init__(self, prefab_id: str, version: str, message: Optional[str] = None):
+        self.prefab_id = prefab_id
+        self.version = version
+        super().__init__(
+            message or f"Prefab {prefab_id}@{version} not found",
+            {"prefab_id": prefab_id, "version": version},
+        )
+
+
+class ValidationError(GatewayError):
+    """参数验证失败"""
+
+    pass
+
+
+class QuotaExceededError(GatewayError):
+    """配额超限"""
+
+    def __init__(self, message: str, limit: int, used: int, quota_type: str):
+        self.limit = limit
+        self.used = used
+        self.quota_type = quota_type
+        super().__init__(
+            message,
+            {"limit": limit, "used": used, "quota_type": quota_type},
+        )
+
+
+class ServiceUnavailableError(GatewayError):
+    """服务不可用"""
+
+    pass
+
+
+class MissingSecretError(GatewayError):
+    """缺少必需的密钥"""
+
+    def __init__(self, prefab_id: str, secret_name: str, instructions: Optional[str] = None):
+        self.prefab_id = prefab_id
+        self.secret_name = secret_name
+        self.instructions = instructions
+        message = f"Missing required secret '{secret_name}' for prefab '{prefab_id}'"
+        if instructions:
+            message += f"\n配置说明: {instructions}"
+        super().__init__(
+            message,
+            {"prefab_id": prefab_id, "secret_name": secret_name, "instructions": instructions},
+        )
+
+
+class AgentContextRequiredError(GatewayError):
+    """缺少 Agent 上下文（文件操作需要在 Agent 环境中运行）"""
+
+    def __init__(self, message: Optional[str] = None):
+        default_message = (
+            "File operations require agent context.\n"
+            "This feature is only available when running in production (called via Gateway Agent invoke).\n"
+            "For third-party integrations, please use upload_input_file() to upload input files."
+        )
+        super().__init__(
+            message or default_message,
+            {"error_code": "MISSING_AGENT_CONTEXT"},
+        )
+

gateway_sdk/models.py

@@ -0,0 +1,213 @@
+"""数据模型"""
+
+from typing import Any, Dict, List, Optional
+from dataclasses import dataclass
+from enum import Enum
+
+
+class CallStatus(str, Enum):
+    """调用状态"""
+
+    SUCCESS = "SUCCESS"
+    FAILED = "FAILED"
+
+
+class StreamEventType(str, Enum):
+    """流式事件类型"""
+
+    START = "start"
+    CONTENT = "content"
+    PROGRESS = "progress"
+    DONE = "done"
+    ERROR = "error"
+
+
+@dataclass
+class PrefabCall:
+    """预制件调用请求"""
+
+    prefab_id: str
+    version: str
+    function_name: str
+    parameters: Dict[str, Any]
+    files: Optional[Dict[str, List[str]]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """转换为字典格式"""
+        inputs: Dict[str, Any] = {"parameters": self.parameters}
+        if self.files:
+            inputs["files"] = self.files
+
+        return {
+            "prefab_id": self.prefab_id,
+            "version": self.version,
+            "function_name": self.function_name,
+            "inputs": inputs,
+        }
+
+
+@dataclass
+class PrefabResult:
+    """预制件执行结果"""
+
+    status: CallStatus
+    output: Optional[Dict[str, Any]] = None
+    error: Optional[Dict[str, Any]] = None
+    job_id: Optional[str] = None
+
+    def is_success(self) -> bool:
+        """判断是否成功"""
+        return self.status == CallStatus.SUCCESS
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """便捷获取输出字段"""
+        if self.output:
+            return self.output.get(key, default)
+        return default
+
+    def get_result(self) -> Any:
+        """
+        获取完整的 output 字典（保持向后兼容）
+        
+        Returns:
+            完整的 output 字典，包含 status, output, files 等
+        """
+        return self.output
+
+    def get_function_result(self) -> Dict[str, Any]:
+        """
+        获取预制件函数的返回值（对应 manifest.returns）
+        
+        这是响应的嵌套结构：
+        - result.output 是 Gateway 的响应
+        - result.output['output'] 是预制件函数的实际返回值
+        
+        Returns:
+            预制件函数的返回值字典
+            
+        Example:
+            >>> result = client.run(...)
+            >>> function_result = result.get_function_result()
+            >>> if function_result.get('success'):
+            ...     print(function_result.get('message'))
+        """
+        if self.output and isinstance(self.output, dict):
+            return self.output.get('output', {})
+        return {}
+
+    def get_business_success(self) -> bool:
+        """
+        判断业务是否成功（检查函数返回值中的 success 字段）
+        
+        注意：
+        - result.is_success() 表示 SDK 调用成功
+        - result.get_business_success() 表示业务逻辑成功
+        
+        Returns:
+            业务是否成功
+            
+        Example:
+            >>> result = client.run(...)
+            >>> if result.is_success() and result.get_business_success():
+            ...     print("调用成功且业务成功")
+        """
+        function_result = self.get_function_result()
+        return function_result.get('success', False)
+
+    def get_business_message(self) -> str:
+        """
+        获取业务消息
+        
+        Returns:
+            业务消息字符串，如果没有消息则返回空字符串
+            
+        Example:
+            >>> result = client.run(...)
+            >>> print(f"消息: {result.get_business_message()}")
+        """
+        function_result = self.get_function_result()
+        return function_result.get('message', '')
+
+    def get_business_error(self) -> Optional[str]:
+        """
+        获取业务错误信息
+        
+        Returns:
+            错误信息字符串，如果没有错误则返回 None
+            
+        Example:
+            >>> result = client.run(...)
+            >>> if not result.get_business_success():
+            ...     print(f"错误: {result.get_business_error()}")
+        """
+        function_result = self.get_function_result()
+        return function_result.get('error')
+
+    def get_business_error_code(self) -> Optional[str]:
+        """
+        获取业务错误代码
+        
+        Returns:
+            错误代码字符串，如果没有错误码则返回 None
+            
+        Example:
+            >>> result = client.run(...)
+            >>> if not result.get_business_success():
+            ...     print(f"错误码: {result.get_business_error_code()}")
+        """
+        function_result = self.get_function_result()
+        return function_result.get('error_code')
+
+    def get_files(self) -> Dict[str, List[str]]:
+        """
+        获取输出文件（S3 URL 列表）
+        
+        Returns:
+            文件字典，key 对应 manifest.files 中定义的 key
+            
+        Example:
+            >>> result = client.run(...)
+            >>> output_files = result.get_files()
+            >>> # 获取特定 key 的输出文件
+            >>> if 'output' in output_files:
+            ...     s3_url = output_files['output'][0]
+        """
+        if self.output:
+            return self.output.get("files", {})
+        return {}
+
+
+@dataclass
+class BatchResult:
+    """批量执行结果"""
+
+    job_id: str
+    status: str
+    results: List[PrefabResult]
+
+    def all_success(self) -> bool:
+        """判断是否全部成功"""
+        return all(r.is_success() for r in self.results)
+
+    def get_failed(self) -> List[PrefabResult]:
+        """获取失败的结果"""
+        return [r for r in self.results if not r.is_success()]
+
+
+@dataclass
+class StreamEvent:
+    """流式事件"""
+
+    type: StreamEventType
+    data: Any
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "StreamEvent":
+        """从字典创建"""
+        event_type = data.get("type", "content")
+        try:
+            event_type_enum = StreamEventType(event_type)
+        except ValueError:
+            event_type_enum = StreamEventType.CONTENT
+
+        return cls(type=event_type_enum, data=data.get("data"))

gateway_sdk/streaming.py

@@ -0,0 +1,41 @@
+"""流式响应处理"""
+
+import json
+from typing import Iterator
+from .models import StreamEvent
+
+
+def parse_sse_stream(response_iter: Iterator[bytes]) -> Iterator[StreamEvent]:
+    """
+    解析 SSE 流式响应
+
+    Args:
+        response_iter: HTTP 响应字节流迭代器
+
+    Yields:
+        StreamEvent: 解析后的流式事件
+    """
+    buffer = b""
+
+    for chunk in response_iter:
+        buffer += chunk
+
+        # 按行分割
+        while b"\n" in buffer:
+            line_bytes, buffer = buffer.split(b"\n", 1)
+            line = line_bytes.decode("utf-8").strip()
+
+            # 跳过空行和注释
+            if not line or line.startswith(":"):
+                continue
+
+            # 解析 SSE 格式：data: {...}
+            if line.startswith("data: "):
+                data_str = line[6:]  # 去掉 "data: " 前缀
+                try:
+                    data = json.loads(data_str)
+                    yield StreamEvent.from_dict(data)
+                except json.JSONDecodeError:
+                    # 忽略无法解析的行
+                    continue
+