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

agent_builder_gateway_sdk-0.2.0.dist-info/METADATA

@@ -0,0 +1,288 @@
+Metadata-Version: 2.4
+Name: agent-builder-gateway-sdk
+Version: 0.2.0
+Summary: Python SDK for Agent Builder Gateway - 用于 AI 构建的程序调用预制件
+Author: Agent Builder Team
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: black>=24.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Gateway SDK
+
+Python SDK for Gateway - 用于调用预制件
+
+## 概述
+
+Gateway SDK 是一个用于调用预制件的 Python SDK。
+
+### 核心特性
+
+- ✅ 简洁的 API
+- ✅ 支持 JWT Token 和 API Key 认证
+- ✅ 流式响应支持（SSE）
+- ✅ 完整的类型提示
+- ✅ 完善的错误处理
+
+## 安装
+
+```bash
+pip install agent-builder-gateway-sdk
+```
+
+## 快速开始
+
+### 初始化客户端
+
+```python
+from gateway_sdk import GatewayClient
+
+# 使用 JWT Token
+client = GatewayClient(jwt_token="your-jwt-token")
+
+# 或使用 API Key
+client = GatewayClient(api_key="sk-xxx")
+```
+
+### 调用预制件
+
+```python
+result = client.run(
+    prefab_id="llm-client",
+    version="1.0.0",
+    function_name="chat",
+    parameters={"messages": [{"role": "user", "content": "Hello"}]}
+)
+
+if result.is_success():
+    print(result.get_result())
+else:
+    print(f"Error: {result.error}")
+```
+
+### 链式调用
+
+```python
+llm = client.prefab("llm-client", "1.0.0")
+result = llm.call("chat", messages=[...], model="gpt-4")
+```
+
+### 流式响应
+
+```python
+for event in client.run(..., stream=True):
+    if event.type == "content":
+        print(event.data, end="", flush=True)
+    elif event.type == "done":
+        print("\n完成")
+```
+
+### 批量调用
+
+```python
+from gateway_sdk import PrefabCall
+
+calls = [
+    PrefabCall(
+        prefab_id="translator",
+        version="1.0.0",
+        function_name="translate",
+        parameters={"text": "Hello", "target": "zh"}
+    ),
+    PrefabCall(
+        prefab_id="translator",
+        version="1.0.0",
+        function_name="translate",
+        parameters={"text": "World", "target": "zh"}
+    )
+]
+
+result = client.run_batch(calls)
+for r in result.results:
+    if r.is_success():
+        print(r.get_result())
+```
+
+### 文件处理
+
+**重要**: SDK 只接收 S3 URL，不负责文件上传/下载。
+
+```python
+# 传递 S3 URL 作为文件输入
+result = client.run(
+    prefab_id="video-processor",
+    version="1.0.0",
+    function_name="extract_audio",
+    parameters={"format": "mp3"},
+    files={"video": ["s3://bucket/input.mp4"]}
+)
+
+# 输出文件也是 S3 URL
+output_files = result.get_files()
+# {"audio": ["s3://bucket/output.mp3"]}
+```
+
+**文件处理流程**:
+1. 📤 使用 S3 客户端上传文件，获取 S3 URL
+2. 📝 将 S3 URL 传递给 SDK
+3. 📥 从返回的 S3 URL 下载结果文件
+
+## API 参考
+
+### GatewayClient
+
+#### 初始化
+
+```python
+GatewayClient(
+    base_url: str = "http://nodeport.sensedeal.vip:30566",
+    api_key: Optional[str] = None,
+    jwt_token: Optional[str] = None,
+    timeout: int = 60
+)
+```
+
+**参数**：
+- `api_key`: API Key
+- `jwt_token`: JWT Token
+- `timeout`: 请求超时时间（秒）
+
+**注意**：必须提供 `api_key` 或 `jwt_token` 之一。
+
+#### 方法
+
+**run()** - 执行单个预制件
+
+```python
+run(
+    prefab_id: str,
+    version: str,
+    function_name: str,
+    parameters: Dict[str, Any],
+    files: Optional[Dict[str, List[str]]] = None,  # 仅接受 S3 URL
+    stream: bool = False
+) -> Union[PrefabResult, Iterator[StreamEvent]]
+```
+
+参数:
+- `files`: 文件输入，格式为 `{"参数名": ["s3://url1", "s3://url2"]}`，**仅接受 S3 URL**
+
+**run_batch()** - 批量执行
+
+```python
+run_batch(calls: List[PrefabCall]) -> BatchResult
+```
+
+**prefab()** - 获取预制件对象
+
+```python
+prefab(prefab_id: str, version: str) -> Prefab
+```
+
+**list_prefabs()** - 列出预制件
+
+```python
+list_prefabs(status: Optional[str] = None) -> List[PrefabInfo]
+```
+
+**get_prefab_spec()** - 获取预制件规格
+
+```python
+get_prefab_spec(prefab_id: str, version: Optional[str] = None) -> Dict[str, Any]
+```
+
+### PrefabResult
+
+预制件执行结果。
+
+**属性**：
+- `status`: 调用状态（SUCCESS / FAILED）
+- `output`: 输出数据
+- `error`: 错误信息
+- `job_id`: 任务 ID
+
+**方法**：
+- `is_success()`: 判断是否成功
+- `get(key, default)`: 获取输出字段
+- `get_result()`: 获取业务结果
+- `get_files()`: 获取输出文件
+
+### StreamEvent
+
+流式事件。
+
+**属性**：
+- `type`: 事件类型（start / content / progress / done / error）
+- `data`: 事件数据
+
+## 错误处理
+
+```python
+from gateway_sdk.exceptions import (
+    GatewayError,
+    AuthenticationError,
+    PrefabNotFoundError,
+    ValidationError,
+    QuotaExceededError,
+    ServiceUnavailableError,
+    MissingSecretError,
+)
+
+try:
+    result = client.run(...)
+except AuthenticationError as e:
+    print(f"认证失败: {e}")
+except PrefabNotFoundError as e:
+    print(f"预制件不存在: {e}")
+except MissingSecretError as e:
+    print(f"缺少密钥: {e.secret_name}")
+except QuotaExceededError as e:
+    print(f"配额超限: {e.used}/{e.limit}")
+except GatewayError as e:
+    print(f"错误: {e}")
+```
+
+## 示例代码
+
+- `examples/basic_usage.py` - 基础用法
+- `examples/streaming.py` - 流式响应
+
+## 常见问题
+
+**Q: 如何处理超时？**
+
+A: 设置 `timeout` 参数：
+```python
+client = GatewayClient(jwt_token="...", timeout=120)
+```
+
+**Q: 如何调试？**
+
+A: 启用日志：
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+```
+
+**Q: 如何停止流式响应？**
+
+A: 使用 `break` 跳出循环：
+```python
+for event in client.run(..., stream=True):
+    if some_condition:
+        break
+```
+
+## 许可证
+
+MIT License

agent_builder_gateway_sdk-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+gateway_sdk/__init__.py,sha256=lgBWm1gkpX8nGx-weoJbpQeHRYygJu5XBhB-ienHq5I,655
+gateway_sdk/auth.py,sha256=Nx0p9FYZHBoQeN8SO2nn7MKH2y02v3UR3M8bYqhQG0w,1165
+gateway_sdk/client.py,sha256=GZh2SyQ_598ex1LebSy6ajN9F3APckn7O1u0TrpmpsU,7708
+gateway_sdk/exceptions.py,sha256=fIrhKC8vIaocXvyK56OEKPGHn8drvGh6nElnyR0Z71A,1897
+gateway_sdk/models.py,sha256=_3MspU7qDNTsCppzWxgr-sNhjdVzu6QVVZHpqw4lVMs,2731
+gateway_sdk/streaming.py,sha256=nwRWxKP5bU8uIMIv_82DyFws9djnEKdAxW6S4L9KtPI,1092
+agent_builder_gateway_sdk-0.2.0.dist-info/METADATA,sha256=tBJr9Lfbo28xXzpyxeTnXRMHqmCR6-VtY7Kx4rgZr8k,5966
+agent_builder_gateway_sdk-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+agent_builder_gateway_sdk-0.2.0.dist-info/licenses/LICENSE,sha256=C3JXUJe4vPtoVe1lp7O4WeGtH71JWYrRaCufEoJ84K0,1076
+agent_builder_gateway_sdk-0.2.0.dist-info/RECORD,,

agent_builder_gateway_sdk-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_builder_gateway_sdk-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Agent Builder Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

gateway_sdk/__init__.py

@@ -0,0 +1,32 @@
+"""
+Agent Builder Gateway SDK
+用于 AI 构建的程序调用预制件的 Python SDK
+"""
+
+from .client import GatewayClient
+from .models import PrefabCall, PrefabResult, BatchResult, StreamEvent
+from .exceptions import (
+    GatewayError,
+    AuthenticationError,
+    PrefabNotFoundError,
+    ValidationError,
+    QuotaExceededError,
+    ServiceUnavailableError,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "GatewayClient",
+    "PrefabCall",
+    "PrefabResult",
+    "BatchResult",
+    "StreamEvent",
+    "GatewayError",
+    "AuthenticationError",
+    "PrefabNotFoundError",
+    "ValidationError",
+    "QuotaExceededError",
+    "ServiceUnavailableError",
+]
+

gateway_sdk/auth.py

@@ -0,0 +1,49 @@
+"""认证管理"""
+
+from typing import Optional
+
+
+class AuthManager:
+    """认证管理器"""
+
+    def __init__(self, api_key: Optional[str] = None, jwt_token: Optional[str] = None):
+        """
+        初始化认证管理器
+
+        Args:
+            api_key: API Key（优先级高）
+            jwt_token: JWT Token
+        """
+        self.api_key = api_key
+        self.jwt_token = jwt_token
+
+    def get_headers(self) -> dict[str, str]:
+        """
+        获取认证请求头
+
+        Returns:
+            认证请求头字典
+        """
+        headers: dict[str, str] = {}
+
+        # API Key 优先
+        if self.api_key:
+            headers["X-API-Key"] = self.api_key
+        elif self.jwt_token:
+            # 确保 Token 格式正确
+            token = self.jwt_token
+            if not token.startswith("Bearer "):
+                token = f"Bearer {token}"
+            headers["Authorization"] = token
+
+        return headers
+
+    def is_authenticated(self) -> bool:
+        """
+        判断是否已配置认证信息
+
+        Returns:
+            是否已配置认证
+        """
+        return bool(self.api_key or self.jwt_token)
+

gateway_sdk/client.py

@@ -0,0 +1,236 @@
+"""Gateway 客户端"""
+
+import httpx
+from typing import Any, Dict, List, Optional, Union, Iterator
+from .auth import AuthManager
+from .models import PrefabCall, PrefabResult, BatchResult, CallStatus, StreamEvent
+from .streaming import parse_sse_stream
+from .exceptions import (
+    GatewayError,
+    AuthenticationError,
+    PrefabNotFoundError,
+    ValidationError,
+    QuotaExceededError,
+    ServiceUnavailableError,
+    MissingSecretError,
+)
+
+
+# Gateway 地址
+DEFAULT_GATEWAY_URL = "http://nodeport.sensedeal.vip:30566"
+
+
+class GatewayClient:
+    """Gateway SDK 主客户端"""
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_GATEWAY_URL,
+        api_key: Optional[str] = None,
+        jwt_token: Optional[str] = None,
+        timeout: int = 60,
+    ):
+        """
+        初始化客户端
+
+        Args:
+            base_url: Gateway 地址（默认使用写死的地址）
+            api_key: API Key（优先级高）
+            jwt_token: JWT Token（用于 AI 构建的程序）
+            timeout: 请求超时时间（秒）
+        """
+        self.base_url = base_url.rstrip("/")
+        self.auth = AuthManager(api_key=api_key, jwt_token=jwt_token)
+        self.timeout = timeout
+
+        if not self.auth.is_authenticated():
+            raise AuthenticationError("必须提供 api_key 或 jwt_token")
+
+    def run(
+        self,
+        prefab_id: str,
+        version: str,
+        function_name: str,
+        parameters: Dict[str, Any],
+        files: Optional[Dict[str, List[str]]] = None,
+        stream: bool = False,
+    ) -> Union[PrefabResult, Iterator[StreamEvent]]:
+        """
+        执行单个预制件
+
+        Args:
+            prefab_id: 预制件 ID
+            version: 版本号
+            function_name: 函数名
+            parameters: 参数字典
+            files: 文件输入（可选）
+            stream: 是否流式返回
+
+        Returns:
+            PrefabResult 或 StreamEvent 迭代器
+
+        Raises:
+            AuthenticationError: 认证失败
+            PrefabNotFoundError: 预制件不存在
+            ValidationError: 参数验证失败
+            QuotaExceededError: 配额超限
+            ServiceUnavailableError: 服务不可用
+            MissingSecretError: 缺少必需的密钥
+        """
+        call = PrefabCall(
+            prefab_id=prefab_id,
+            version=version,
+            function_name=function_name,
+            parameters=parameters,
+            files=files,
+        )
+
+        if stream:
+            return self._run_streaming(call)
+        else:
+            result = self.run_batch([call])
+            return result.results[0]
+
+    def run_batch(self, calls: List[PrefabCall]) -> BatchResult:
+        """
+        批量执行预制件
+
+        Args:
+            calls: 预制件调用列表
+
+        Returns:
+            BatchResult
+
+        Raises:
+            同 run() 方法
+        """
+        url = f"{self.base_url}/v1/run"
+        headers = self.auth.get_headers()
+        headers["Content-Type"] = "application/json"
+
+        payload = {"calls": [call.to_dict() for call in calls]}
+
+        try:
+            with httpx.Client(timeout=self.timeout) as client:
+                response = client.post(url, json=payload, headers=headers)
+                self._handle_error_response(response)
+
+                data = response.json()
+                results = [
+                    PrefabResult(
+                        status=CallStatus(r["status"]),
+                        output=r.get("output"),
+                        error=r.get("error"),
+                        job_id=data.get("job_id"),
+                    )
+                    for r in data["results"]
+                ]
+
+                return BatchResult(job_id=data["job_id"], status=data["status"], results=results)
+
+        except httpx.TimeoutException:
+            raise ServiceUnavailableError("请求超时")
+        except httpx.RequestError as e:
+            raise ServiceUnavailableError(f"网络请求失败: {str(e)}")
+
+    def _run_streaming(self, call: PrefabCall) -> Iterator[StreamEvent]:
+        """
+        流式执行预制件
+
+        Args:
+            call: 预制件调用
+
+        Yields:
+            StreamEvent
+        """
+        url = f"{self.base_url}/v1/run"
+        headers = self.auth.get_headers()
+        headers["Content-Type"] = "application/json"
+
+        payload = {"calls": [call.to_dict()]}
+
+        try:
+            with httpx.Client(timeout=self.timeout) as client:
+                with client.stream("POST", url, json=payload, headers=headers) as response:
+                    self._handle_error_response(response)
+
+                    # 解析 SSE 流
+                    yield from parse_sse_stream(response.iter_bytes())
+
+        except httpx.TimeoutException:
+            raise ServiceUnavailableError("请求超时")
+        except httpx.RequestError as e:
+            raise ServiceUnavailableError(f"网络请求失败: {str(e)}")
+
+    def _handle_error_response(self, response: httpx.Response) -> None:
+        """
+        处理错误响应
+
+        Args:
+            response: HTTP 响应
+
+        Raises:
+            对应的异常
+        """
+        if response.status_code < 400:
+            return
+
+        try:
+            error_data = response.json()
+            detail = error_data.get("detail", "Unknown error")
+
+            # 解析错误详情
+            if isinstance(detail, dict):
+                error_code = detail.get("error_code", "UNKNOWN_ERROR")
+                message = detail.get("message", str(detail))
+            else:
+                error_code = "UNKNOWN_ERROR"
+                message = str(detail)
+
+        except Exception:
+            error_code = "UNKNOWN_ERROR"
+            # 对于流式响应，需要先读取内容
+            try:
+                error_text = response.text
+            except Exception:
+                # 如果无法读取，先读取响应再获取文本
+                try:
+                    response.read()
+                    error_text = response.text
+                except Exception:
+                    error_text = "Unable to read error response"
+            message = f"HTTP {response.status_code}: {error_text}"
+
+        # 根据状态码和错误码抛出对应异常
+        if response.status_code == 401 or response.status_code == 403:
+            raise AuthenticationError(message)
+        elif response.status_code == 404:
+            raise PrefabNotFoundError("unknown", "unknown", message)
+        elif response.status_code == 422:
+            raise ValidationError(message)
+        elif response.status_code == 429:
+            # 配额超限
+            if isinstance(detail, dict):
+                raise QuotaExceededError(
+                    message,
+                    limit=detail.get("limit", 0),
+                    used=detail.get("used", 0),
+                    quota_type=detail.get("quota_type", "unknown"),
+                )
+            else:
+                raise QuotaExceededError(message, 0, 0, "unknown")
+        elif response.status_code == 400 and error_code == "MISSING_SECRET":
+            # 缺少密钥
+            if isinstance(detail, dict):
+                raise MissingSecretError(
+                    prefab_id=detail.get("prefab_id", "unknown"),
+                    secret_name=detail.get("secret_name", "unknown"),
+                    instructions=detail.get("instructions"),
+                )
+            else:
+                raise MissingSecretError("unknown", "unknown")
+        elif response.status_code >= 500:
+            raise ServiceUnavailableError(message)
+        else:
+            raise GatewayError(message, {"error_code": error_code})
+

gateway_sdk/exceptions.py

@@ -0,0 +1,72 @@
+"""异常定义"""
+
+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},
+        )
+

gateway_sdk/models.py

@@ -0,0 +1,114 @@
+"""数据模型"""
+
+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:
+        """获取业务结果"""
+        if self.output:
+            return self.output.get("result", self.output)
+        return None
+
+    def get_files(self) -> Dict[str, List[str]]:
+        """获取输出文件"""
+        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
+