refactor(core): implement lazy loading for server module to handle optional dependencies

This change introduces a lazy loading mechanism for the server module to avoid import errors when optional dependencies are not installed. The server-related exports are now imported on-demand through __getattr__, with clear error messages when required optional dependencies are missing.

The implementation includes:
- TYPE_CHECKING import for type hints during development
- Delayed imports wrapped in TYPE_CHECKING blocks
- __getattr__ function to handle runtime imports
- Clear error messages directing users to install optional dependencies
- Server exports defined in _SERVER_EXPORTS set for tracking

This resolves issues where the package would fail to import when server optional dependencies were not available.

refactor(core): 实现服务器模块的延迟加载以处理可选依赖

此更改引入了服务器模块的延迟加载机制，以避免在未安装可选依赖项时出现导入错误。现在通过 __getattr__ 按需导入服务器相关导出，并在缺少必需的可选依赖项时提供清晰的错误消息。

实现包括：
- 用于开发期间类型提示的 TYPE_CHECKING 导入
- 包装在 TYPE_CHECKING 块中的延迟导入
- 用于处理运行时导入的 __getattr__ 函数
- 指向用户安装可选依赖项的清晰错误消息
- 定义在 _SERVER_EXPORTS 集合中用于跟踪的服务器导出

这解决了在服务器可选依赖项不可用时包导入失败的问题。

Change-Id: I9d8f7dd8e5c6d34dfd0619714ead5aea22105293
Signed-off-by: OhYee <[email protected]>

Author: OhYee

agentrun/__init__.py

@@ -16,6 +16,8 @@
 - Integration: 框架集成 / Framework integration
 """
 
+from typing import TYPE_CHECKING
+
 __version__ = "0.0.8"
 
 # Agent Runtime
@@ -87,27 +89,50 @@
     SandboxClient,
     Template,
 )
-# Server
-from agentrun.server import (
-    AgentRequest,
-    AgentResult,
-    AgentRunServer,
-    AsyncInvokeAgentHandler,
-    InvokeAgentHandler,
-    Message,
-    MessageRole,
-    OpenAIProtocolHandler,
-    ProtocolHandler,
-    SyncInvokeAgentHandler,
-)
 # ToolSet
 from agentrun.toolset import ToolSet, ToolSetClient
+from agentrun.utils.config import Config
 from agentrun.utils.exception import (
     ResourceAlreadyExistError,
     ResourceNotExistError,
 )
 from agentrun.utils.model import Status
 
+# Server - 延迟导入以避免可选依赖问题
+# Type hints for IDE and type checkers
+if TYPE_CHECKING:
+    from agentrun.server import (
+        AgentEvent,
+        AgentEventItem,
+        AgentRequest,
+        AgentResult,
+        AgentResultItem,
+        AgentReturnType,
+        AgentRunServer,
+        AguiEventNormalizer,
+        AGUIProtocolConfig,
+        AGUIProtocolHandler,
+        AsyncAgentEventGenerator,
+        AsyncAgentResultGenerator,
+        AsyncInvokeAgentHandler,
+        BaseProtocolHandler,
+        EventType,
+        InvokeAgentHandler,
+        MergeOptions,
+        Message,
+        MessageRole,
+        OpenAIProtocolConfig,
+        OpenAIProtocolHandler,
+        ProtocolConfig,
+        ProtocolHandler,
+        ServerConfig,
+        SyncAgentEventGenerator,
+        SyncAgentResultGenerator,
+        SyncInvokeAgentHandler,
+        Tool,
+        ToolCall,
+    )
+
 __all__ = [
     ######## Agent Runtime ########
     # base
@@ -185,22 +210,106 @@
     ######## ToolSet ########
     "ToolSetClient",
     "ToolSet",
-    ######## Server ########
+    ######## Server (延迟加载) ########
+    # Server
     "AgentRunServer",
+    # Config
+    "ServerConfig",
+    "ProtocolConfig",
+    "OpenAIProtocolConfig",
+    "AGUIProtocolConfig",
+    # Request/Response Models
     "AgentRequest",
-    "AgentResponse",
+    "AgentEvent",
     "AgentResult",
-    "AgentStreamResponse",
+    "Message",
+    "MessageRole",
+    "Tool",
+    "ToolCall",
+    # Event Types
+    "EventType",
+    # Type Aliases
+    "AgentEventItem",
+    "AgentResultItem",
+    "AgentReturnType",
+    "SyncAgentEventGenerator",
+    "SyncAgentResultGenerator",
+    "AsyncAgentEventGenerator",
+    "AsyncAgentResultGenerator",
     "InvokeAgentHandler",
     "AsyncInvokeAgentHandler",
     "SyncInvokeAgentHandler",
-    "Message",
-    "MessageRole",
+    # Protocol Base
     "ProtocolHandler",
+    "BaseProtocolHandler",
+    # Protocol - OpenAI
     "OpenAIProtocolHandler",
-    "AgentStreamIterator",
+    # Protocol - AG-UI
+    "AGUIProtocolHandler",
+    # Event Normalizer
+    "AguiEventNormalizer",
+    # Helpers
+    "MergeOptions",
     ######## Others ########
-    "Status",
     "ResourceNotExistError",
     "ResourceAlreadyExistError",
+    "Config",
 ]
+
+# Server 模块的所有导出
+_SERVER_EXPORTS = {
+    "AgentRunServer",
+    "ServerConfig",
+    "ProtocolConfig",
+    "OpenAIProtocolConfig",
+    "AGUIProtocolConfig",
+    "AgentRequest",
+    "AgentEvent",
+    "AgentResult",
+    "Message",
+    "MessageRole",
+    "Tool",
+    "ToolCall",
+    "EventType",
+    "AgentEventItem",
+    "AgentResultItem",
+    "AgentReturnType",
+    "SyncAgentEventGenerator",
+    "SyncAgentResultGenerator",
+    "AsyncAgentEventGenerator",
+    "AsyncAgentResultGenerator",
+    "InvokeAgentHandler",
+    "AsyncInvokeAgentHandler",
+    "SyncInvokeAgentHandler",
+    "ProtocolHandler",
+    "BaseProtocolHandler",
+    "OpenAIProtocolHandler",
+    "AGUIProtocolHandler",
+    "AguiEventNormalizer",
+    "MergeOptions",
+}
+
+
+def __getattr__(name: str):
+    """延迟加载 server 模块的导出，避免可选依赖导致导入失败
+
+    当用户访问 server 相关的类时，才尝试导入 server 模块。
+    如果 server 可选依赖未安装，会抛出清晰的错误提示。
+    """
+    if name in _SERVER_EXPORTS:
+        try:
+            from agentrun import server
+
+            return getattr(server, name)
+        except ImportError as e:
+            # 检查是否是缺少可选依赖导致的错误
+            if "fastapi" in str(e) or "uvicorn" in str(e):
+                raise ImportError(
+                    f"'{name}' requires the 'server' optional dependencies. "
+                    "Install with: pip install agentrun-sdk[server]\n"
+                    f"Original error: {e}"
+                ) from e
+            # 其他导入错误继续抛出
+            raise
+
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")