wisruntime 0.1.0__py3-none-any.whl

wisruntime/__init__.py

@@ -0,0 +1,91 @@
+"""wisruntime — 企业级 Agent Runtime SDK。
+
+让 AI 工程师用框架原生 API 构建 Agent，数行代码获得生产级服务端点。
+
+Quick Start:
+    from wisruntime import create_server
+    from wisruntime.model import AgentRequest, Message
+
+    async def my_agent(request: AgentRequest):
+        '''用户自定义的 Agent 逻辑。yield str 即可，SDK 自动处理归一化和序列化。'''
+        async for chunk in llm.astream(messages):
+            yield chunk.content
+
+    create_server(my_agent).start(port=8000)
+    # → Dify SSE 服务就绪: POST /dify/v1/chat-messages
+"""
+
+from wisruntime.config import Config, CredentialContext
+from wisruntime.exceptions import ConfigError, InvokerError, ProtocolError, WisRuntimeError
+from wisruntime.model import (
+    AgentRequest,
+    CustomEvent,
+    DoneEvent,
+    ErrorEvent,
+    FileOutputEvent,
+    Message,
+    ReasoningDeltaEvent,
+    SubAgentEndEvent,
+    SubAgentStartEvent,
+    TextDeltaEvent,
+    ToolCallEndEvent,
+    ToolCallStartEvent,
+    UsageEvent,
+)
+
+# Server 层延迟导入 — 避免在非 Web 场景拉动 fastapi/uvicorn
+# 用户需要 Server 时显式导入: from wisruntime.server import create_server
+
+
+def create_server(invoke_agent, *, protocols=None, config=None, checkpoint_enabled=False):
+    """创建 WisRuntimeServer 实例 (顶层入口 API)。
+
+    接收用户编写的 invoke_agent 函数，返回可启动的 Server 实例。
+    Server 默认启用 DifyHandler，可通过 protocols 参数添加更多协议处理器。
+
+    Args:
+        invoke_agent: 用户函数，签名为 async def fn(request: AgentRequest) -> AsyncGenerator。
+        protocols: 协议处理器列表，默认 [DifyHandler()]。
+        config: ServerConfig 实例，配置 CORS、健康检查路径等。
+        checkpoint_enabled: 是否启用 Checkpoint 自动持久化 (Phase 3)。
+
+    Returns:
+        WisRuntimeServer 实例，调用 .start(port=8000) 或 .as_fastapi_app() 启动服务。
+
+    Demo:
+        >>> from wisruntime import create_server
+        >>> async def my_agent(request):
+        ...     yield "你好，我是 AI 助手"
+        >>> server = create_server(my_agent)
+        >>> # server.start(port=8000)
+    """
+    from wisruntime.server.server import WisRuntimeServer, ServerConfig
+    from wisruntime.server.dify_handler import DifyHandler
+
+    _config = config or ServerConfig()
+    _protocols = protocols or [DifyHandler()]
+    return WisRuntimeServer(invoke_agent=invoke_agent, protocols=_protocols, config=_config)
+
+
+__all__ = [
+    "create_server",
+    "Config",
+    "CredentialContext",
+    "AgentRequest",
+    "Message",
+    "TextDeltaEvent",
+    "ReasoningDeltaEvent",
+    "ToolCallStartEvent",
+    "ToolCallEndEvent",
+    "SubAgentStartEvent",
+    "SubAgentEndEvent",
+    "FileOutputEvent",
+    "UsageEvent",
+    "ErrorEvent",
+    "CustomEvent",
+    "DoneEvent",
+    "WisRuntimeError",
+    "ConfigError",
+    "ProtocolError",
+    "InvokerError",
+]

wisruntime/config.py

@@ -0,0 +1,119 @@
+"""全局配置与凭证上下文管理。
+
+Config 提供三级 API-KEY 获取 (显式传入 > contextvars > 环境变量),
+CredentialContext 基于 contextvars 实现请求级凭证注入 (Server 模式)。
+
+参考: AgentRun SDK 的 Config + CredentialContext 设计。
+"""
+
+import os
+from contextvars import ContextVar
+
+# ============================================================================
+# CredentialContext — 请求级 API-KEY 注入
+# ============================================================================
+# 基于 contextvars，每个异步请求有独立的上下文副本。
+# 在 Server 模式下，ApiKeyMiddleware 从请求的 Bearer 头提取 API-KEY 并注入。
+# 在本地开发模式下，contextvars 为空，回退到环境变量。
+
+_request_api_key: ContextVar[str | None] = ContextVar("_request_api_key", default=None)
+
+
+class CredentialContext:
+    """请求级凭证上下文管理器。
+
+    提供 get/set 方法操作 contextvars 中的 API-KEY。
+    ApiKeyMiddleware 在每次 HTTP 请求时调用 set，请求结束时自动复位。
+
+    Demo:
+        >>> # Server 中间件注入
+        >>> token = CredentialContext.set_request_api_key("wisa-sk-xxx")
+        >>> CredentialContext.get_request_api_key()
+        'wisa-sk-xxx'
+        >>> # 请求结束后 contextvars 自动复位到默认值 None
+    """
+
+    @staticmethod
+    def get_request_api_key() -> str | None:
+        """获取当前请求上下文中的 API-KEY。
+
+        仅在 Server 模式的请求处理期间有效。
+        本地开发时返回 None，由 Config 回退到环境变量。
+        """
+        return _request_api_key.get()
+
+    @staticmethod
+    def set_request_api_key(key: str | None) -> None:
+        """设置当前请求上下文中的 API-KEY。
+
+        通常由 ApiKeyMiddleware 调用，注入从 HTTP 请求头解析的 API-KEY。
+        """
+        _request_api_key.set(key)
+
+
+# ============================================================================
+# Config — 全局配置
+# ============================================================================
+
+
+class Config:
+    """SDK 全局配置。
+
+    管理 API-KEY、WIS Hub 端点、超时等全局设置。
+    凭证获取遵循三级优先级: 显式传入 → contextvars → 环境变量。
+
+    Demo:
+        >>> # 方式 1: 显式传入 (本地开发)
+        >>> config = Config(api_key="wisa-sk-xxx", hub_endpoint="https://hub.example.com")
+        >>> # 方式 2: 环境变量 (容器部署)
+        >>> # export WIS_HUB_API_KEY="wisa-sk-xxx"
+        >>> config = Config()  # 自动从环境变量读取
+        >>> config.api_key
+        'wisa-sk-xxx'
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        hub_endpoint: str | None = None,
+        timeout: int = 600,
+    ):
+        """初始化 Config。
+
+        Args:
+            api_key: 统一 API-KEY。None 表示从环境变量或 contextvars 获取。
+            hub_endpoint: WIS Hub 地址。None 时使用默认内置地址。
+            timeout: HTTP 请求超时秒数，默认 600 秒。
+        """
+        self._api_key = api_key
+        self._hub_endpoint = hub_endpoint
+        self.timeout = timeout
+
+    @property
+    def api_key(self) -> str | None:
+        """获取 API-KEY，按三级优先级: 显式传入 > contextvars > 环境变量。"""
+        if self._api_key:
+            return self._api_key
+        ctx_key = CredentialContext.get_request_api_key()
+        if ctx_key:
+            return ctx_key
+        return os.environ.get("WIS_HUB_API_KEY")
+
+    @property
+    def hub_endpoint(self) -> str:
+        """获取 WIS Hub 地址。"""
+        if self._hub_endpoint:
+            return self._hub_endpoint
+        return os.environ.get("WIS_HUB_ENDPOINT", "https://hub.wis.example.com")
+
+    def with_api_key(self, api_key: str) -> "Config":
+        """创建一个携带指定 API-KEY 的新 Config 实例 (不影响原实例)。
+
+        Demo:
+            >>> config = Config()
+            >>> config2 = config.with_api_key("custom-key")
+            >>> config2.api_key
+            'custom-key'
+        """
+        new = Config(api_key=api_key, hub_endpoint=self._hub_endpoint, timeout=self.timeout)
+        return new

wisruntime/exceptions.py

@@ -0,0 +1,56 @@
+"""自定义异常定义。
+
+wisruntime 内部使用的异常类型，帮助区分 SDK 内部错误和用户代码错误。
+"""
+
+
+class WisRuntimeError(Exception):
+    """wisruntime 基础异常。
+
+    所有 SDK 内部抛出的异常都继承自此类型，方便用户统一捕获。
+
+    Demo:
+        >>> try:
+        ...     raise WisRuntimeError("配置错误")
+        ... except WisRuntimeError as e:
+        ...     print(e)
+        配置错误
+    """
+
+    pass
+
+
+class ConfigError(WisRuntimeError):
+    """配置相关错误。
+
+    当必需的配置项缺失或无效时抛出 (如未设置 API-KEY 却尝试创建 MCPClient)。
+
+    Demo:
+        >>> raise ConfigError("缺少 WIS_HUB_API_KEY，请设置环境变量或显式传入 api_key")
+    """
+
+    pass
+
+
+class ProtocolError(WisRuntimeError):
+    """协议解析/序列化错误。
+
+    当协议请求格式不正确或序列化失败时抛出。
+
+    Demo:
+        >>> raise ProtocolError("Dify 请求缺少必需的 query 字段")
+    """
+
+    pass
+
+
+class InvokerError(WisRuntimeError):
+    """AgentInvoker 调用错误。
+
+    当用户函数不符合预期格式时抛出。
+
+    Demo:
+        >>> raise InvokerError("invoke_agent 函数不能是同步生成器，请使用异步生成器 (async def)")
+    """
+
+    pass

wisruntime/model.py

@@ -0,0 +1,326 @@
+"""wisruntime 核心数据模型。
+
+定义整个 SDK 的稳定数据契约:
+- CanonicalEvent: 框架事件与协议事件之间的中间表示 (11 种类型)
+- AgentRequest: 协议无关的归一化请求模型
+- Message: 归一化消息模型
+
+这些类型是所有 Adapter (产出端) 和 ProtocolHandler (消费端) 的唯一契约。
+"""
+
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+# ============================================================================
+# CanonicalEvent — 11 种事件类型
+# ============================================================================
+# 设计参考: LangChain v2/v3, Dify/Wisknow, AgentRun 四套事件体系。
+# 使用 Pydantic discriminated union 实现类型安全的事件分发。
+
+
+class TextDeltaEvent(BaseModel):
+    """文本增量事件。
+
+    对应模型流式输出的内容增量。用户 yield 的 str 会被 AgentInvoker 自动转换为此类型。
+
+    Demo:
+        >>> event = TextDeltaEvent(type="text_delta", delta="你好")
+        >>> event.model_dump_json()
+        '{"type":"text_delta","delta":"你好"}'
+    """
+
+    type: Literal["text_delta"] = "text_delta"
+    delta: str
+
+
+class ReasoningDeltaEvent(BaseModel):
+    """推理增量事件 (Chain-of-Thought)。
+
+    对应模型的思维链输出，与正文内容分开传输。在 Dify 协议中映射为 reasoning_chunk。
+
+    Demo:
+        >>> event = ReasoningDeltaEvent(type="reasoning_delta", delta="让我想一想...")
+        >>> event.delta
+        '让我想一想...'
+    """
+
+    type: Literal["reasoning_delta"] = "reasoning_delta"
+    delta: str
+
+
+class ToolCallStartEvent(BaseModel):
+    """工具调用开始事件。
+
+    工具调用的参数可能分块流式到达，args_delta 是增量而非完整参数。
+    tool_call_id 由框架或 Adapter 提供，用于和后续 ToolCallEnd 配对。
+
+    Demo:
+        >>> event = ToolCallStartEvent(
+        ...     type="tool_call_start",
+        ...     tool_call_id="call_001",
+        ...     name="search",
+        ...     args_delta='{"query": "天气"}'
+        ... )
+        >>> event.tool_call_id
+        'call_001'
+    """
+
+    type: Literal["tool_call_start"] = "tool_call_start"
+    tool_call_id: str
+    name: str
+    args_delta: str = ""
+
+
+class ToolCallEndEvent(BaseModel):
+    """工具调用结束事件。
+
+    携带工具执行结果或错误信息。tool_call_id 与对应的 ToolCallStart 配对。
+    result 和 error 互斥: 成功时 result 有值，失败时 error 有值。
+
+    Demo:
+        >>> # 成功场景
+        >>> event = ToolCallEndEvent(
+        ...     type="tool_call_end",
+        ...     tool_call_id="call_001",
+        ...     result={"temperature": 25},
+        ... )
+        >>> # 失败场景
+        >>> event = ToolCallEndEvent(
+        ...     type="tool_call_end",
+        ...     tool_call_id="call_002",
+        ...     error="Tool execution timeout",
+        ... )
+    """
+
+    type: Literal["tool_call_end"] = "tool_call_end"
+    tool_call_id: str
+    result: Any | None = None
+    error: str | None = None
+
+
+class SubAgentStartEvent(BaseModel):
+    """子 Agent 开始运行事件。
+
+    对应 Wisknow/灵知 平台的子代理场景。主 Agent 委派任务给子 Agent 时触发。
+
+    Demo:
+        >>> event = SubAgentStartEvent(
+        ...     type="subagent_start",
+        ...     agent_name="健康顾问",
+        ...     run_id="run-abc-123",
+        ...     task_description="分析用户的健康数据并给出建议",
+        ... )
+    """
+
+    type: Literal["subagent_start"] = "subagent_start"
+    agent_name: str
+    run_id: str
+    task_description: str = ""
+
+
+class SubAgentEndEvent(BaseModel):
+    """子 Agent 运行结束事件。
+
+    run_id 与对应的 SubAgentStart 配对。status 为 "completed" 或 "failed"。
+
+    Demo:
+        >>> event = SubAgentEndEvent(
+        ...     type="subagent_end",
+        ...     agent_name="健康顾问",
+        ...     run_id="run-abc-123",
+        ...     status="completed",
+        ... )
+    """
+
+    type: Literal["subagent_end"] = "subagent_end"
+    agent_name: str
+    run_id: str
+    status: Literal["completed", "failed"]
+
+
+class FileOutputEvent(BaseModel):
+    """文件输出事件。
+
+    对应多模态输出: 图片、音频、视频、文件等。
+
+    Demo:
+        >>> event = FileOutputEvent(
+        ...     type="file_output",
+        ...     file_id="file-001",
+        ...     file_type="image",
+        ...     url="https://cdn.example.com/generated.png",
+        ...     belongs_to="assistant",
+        ... )
+    """
+
+    type: Literal["file_output"] = "file_output"
+    file_id: str
+    file_type: str
+    url: str
+    belongs_to: Literal["user", "assistant"]
+
+
+class UsageEvent(BaseModel):
+    """Token 用量统计事件。
+
+    通常在流结束前发送，提供本次调用的 token 消耗统计。
+
+    Demo:
+        >>> event = UsageEvent(type="usage", prompt_tokens=100, completion_tokens=50, total_tokens=150)
+    """
+
+    type: Literal["usage"] = "usage"
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+
+
+class ErrorEvent(BaseModel):
+    """错误事件。
+
+    出现此事件后流应立即终止。recoverable 标记错误是否可通过重试解决。
+
+    Demo:
+        >>> # 可恢复错误 (如暂时网络问题)
+        >>> event = ErrorEvent(type="error", message="网络超时", code="TIMEOUT", recoverable=True)
+        >>> # 不可恢复错误 (如参数校验失败)
+        >>> event = ErrorEvent(type="error", message="无效的输入", code="INVALID_INPUT", recoverable=False)
+    """
+
+    type: Literal["error"] = "error"
+    message: str
+    code: str | None = None
+    recoverable: bool = False
+
+
+class CustomEvent(BaseModel):
+    """自定义事件 (扩展通道)。
+
+    用于框架特有或应用特有的事件类型，不需要修改 CanonicalEvent 体系。
+    对应 LangChain v2 的 on_custom_event 和灵知平台的 todo_update / recommendation_card 等。
+
+    Demo:
+        >>> event = CustomEvent(
+        ...     type="custom",
+        ...     name="todo_update",
+        ...     payload={"todos": [{"id": "1", "content": "搜索数据", "status": "in_progress"}]},
+        ... )
+    """
+
+    type: Literal["custom"] = "custom"
+    name: str
+    payload: dict = Field(default_factory=dict)
+
+
+class DoneEvent(BaseModel):
+    """流结束标记事件。
+
+    由 AgentInvoker 在用户函数正常退出时自动插入。
+    协议层 (如 DifyHandler) 根据此事件生成对应的流结束信号 (如 message_end)。
+
+    Demo:
+        >>> event = DoneEvent(type="done", metadata={"total_tokens": 150})
+    """
+
+    type: Literal["done"] = "done"
+    metadata: dict = Field(default_factory=dict)
+
+
+# ============================================================================
+# Discriminated Union — 类型安全的事件分发
+# ============================================================================
+# 通过 Literal discriminator，Pydantic 可以根据 type 字段自动解析为正确的子类。
+# 消费端 (ProtocolHandler) 可以用 match/case 或 isinstance 来分发处理。
+
+CanonicalEvent = Annotated[
+    TextDeltaEvent
+    | ReasoningDeltaEvent
+    | ToolCallStartEvent
+    | ToolCallEndEvent
+    | SubAgentStartEvent
+    | SubAgentEndEvent
+    | FileOutputEvent
+    | UsageEvent
+    | ErrorEvent
+    | CustomEvent
+    | DoneEvent,
+    Field(discriminator="type"),
+]
+"""CanonicalEvent — wisruntime 的核心数据契约。
+
+所有 Adapter 产出此类型，所有 ProtocolHandler 消费此类型。
+11 种事件覆盖: 内容流 (Text/Reasoning/File), 工具调用生命周期,
+子 Agent 生命周期, 元事件 (Usage/Error/Custom/Done)。
+
+消费方式:
+    async for event in generator:
+        match event.type:
+            case "text_delta":      process_text(event.delta)
+            case "reasoning_delta": process_reasoning(event.delta)
+            case "tool_call_start": process_tool_start(event)
+            case "done":            break
+"""
+
+
+# ============================================================================
+# AgentRequest + Message — 归一化请求模型
+# ============================================================================
+
+
+class Message(BaseModel):
+    """归一化消息模型。
+
+    协议无关的消息表示，对应 OpenAI chat message 格式。
+
+    Demo:
+        >>> msg = Message(role="user", content="你好")
+        >>> msg = Message(role="assistant", content=[{"type": "text", "text": "你好!"}])
+    """
+
+    role: Literal["system", "user", "assistant", "tool"]
+    content: str | list[dict]
+    """文本字符串或多模态内容块列表。"""
+
+    name: str | None = None
+
+
+class AgentRequest(BaseModel):
+    """协议无关的归一化请求模型。
+
+    各 ProtocolHandler (Dify/AGUI/...) 将各自的请求格式解析为此模型，
+    然后传给 AgentInvoker 调用用户函数。
+
+    Demo:
+        >>> request = AgentRequest(
+        ...     messages=[Message(role="user", content="今天天气怎么样?")],
+        ...     stream=True,
+        ...     conversation_id="conv-001",
+        ...     user_id="user-001",
+        ...     headers={"authorization": "Bearer xxx"},
+        ... )
+    """
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    messages: list[Message]
+    """归一化后的消息列表。由 ProtocolHandler 从原始请求中提取。"""
+
+    stream: bool = True
+    """是否流式输出。True = SSE Streaming, False = 阻塞模式返回完整结果。"""
+
+    conversation_id: str | None = None
+    """会话 ID，用于多轮对话上下文关联和 Checkpoint 恢复。"""
+
+    user_id: str | None = None
+    """用户标识，用于审计和个性化。"""
+
+    headers: dict[str, str] = Field(default_factory=dict)
+    """关键 HTTP 请求头的副本，可安全跨线程传递。"""
+
+    raw_request: Any | None = None
+    """原始 Starlette Request 对象。仅在本地开发时可用，不能跨线程传递。"""
+
+    protocol_extensions: dict = Field(default_factory=dict)
+    """协议特有字段。如 Dify 的 inputs, files 等。由各 ProtocolHandler 解析后放入此字典。"""