bolt-boot 0.1.0__py3-none-any.whl

bolt/__init__.py

@@ -0,0 +1,23 @@
+"""Bolt - AI-Native FastAPI Framework"""
+
+__version__ = "0.1.0"
+
+from typing import Any
+
+__all__ = ["App", "create_app", "get_settings"]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "App":
+        from bolt.core.app import App
+
+        return App
+    if name == "create_app":
+        from bolt.core.app import create_app
+
+        return create_app
+    if name == "get_settings":
+        from bolt.core.config import get_settings
+
+        return get_settings
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

bolt/__main__.py

@@ -0,0 +1,18 @@
+"""内置演示应用，``python -m bolt`` / 镜像默认 CMD 的可运行入口。
+
+提供一个最小可用的 Bolt 实例（健康检查、指标等基础端点），
+用于容器镜像冒烟与快速验证。业务应用请自行 ``create_app``
+并覆盖容器的 CMD。
+"""
+
+from __future__ import annotations
+
+from bolt.core.app import create_app
+
+app = create_app(title="Bolt Demo")
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)

bolt/agent/__init__.py

@@ -0,0 +1,39 @@
+"""Agent 模块 - 底层由 OxyGent MAS 驱动。
+
+提供 AI Agent 开发能力：
+- BoltAgent: Agent 基类（对话/工具循环/流式，OxyGent ReAct 驱动）
+- ToolRegistry: 工具注册表
+- ConversationMemory: 会话记忆（内存/Redis/数据库）
+- MultiAgentSystem: 多 Agent 编排（master 委派 sub_agents）
+"""
+
+from bolt.agent.base import AgentResult, BoltAgent, tool
+from bolt.agent.memory import (
+    ConversationMemory,
+    DatabaseConversationMemory,
+    RedisConversationMemory,
+    create_memory,
+)
+from bolt.agent.messages import ChatMessage
+from bolt.agent.oxy.mas_api import AgentSpec, AgentStreamEvent, MultiAgentSystem
+from bolt.agent.tools import Tool, ToolRegistry
+
+__all__ = [
+    # Agent
+    "BoltAgent",
+    "AgentResult",
+    "tool",
+    "ChatMessage",
+    # 工具
+    "ToolRegistry",
+    "Tool",
+    # 多 Agent 编排
+    "MultiAgentSystem",
+    "AgentSpec",
+    "AgentStreamEvent",
+    # 记忆
+    "ConversationMemory",
+    "RedisConversationMemory",
+    "DatabaseConversationMemory",
+    "create_memory",
+]

bolt/agent/base.py

@@ -0,0 +1,282 @@
+"""Agent 基类 - 底层由 OxyGent MAS 驱动。
+
+BoltAgent 的对话/工具循环/多 Agent 委派全部由内嵌的 OxyGent 引擎完成：
+- 有工具的 Agent 映射为 OxyGent ``ReActAgent``（完整的工具调用循环）
+- 无工具的 Agent 映射为 ``ChatAgent``
+- MAS 实例进程级单例，懒启动（首次调用时初始化）
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections import OrderedDict
+from collections.abc import AsyncIterator, Callable
+from typing import TYPE_CHECKING, Any, ParamSpec, TypeVar
+
+from pydantic import BaseModel, Field
+
+from bolt.agent.messages import ChatMessage
+from bolt.agent.tools import Tool
+from bolt.core.config import get_settings
+
+if TYPE_CHECKING:
+    from bolt.agent.memory import ConversationMemory
+    from bolt.agent.oxy.engine import OxyEngine
+
+__all__ = [
+    "BoltAgent",
+    "AgentResult",
+    "tool",
+]
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+# ============ 工具装饰器 ============
+
+
+def tool(
+    name: str | None = None,
+    description: str = "",
+) -> Callable[..., Any]:
+    """Tool 装饰器 - 标记方法为可被 Agent 调用的工具。
+
+    装饰后原函数原样返回（可直接调用），仅附加工具元信息；
+    元信息在 MAS 启动时桥接为 OxyGent FunctionTool。
+
+    用法:
+        @tool(description="搜索知识库")
+        async def search_kb(self, query: str) -> str:
+            return await self.kb.search(query)
+    """
+
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        tool_name = name or func.__name__
+        tool_desc = description or func.__doc__ or ""
+
+        # 附加 Tool 元信息（MAS 启动时桥接为 FunctionTool）。
+        # 动态属性经 setattr 注入：ruff B010 豁免 + 规避函数对象属性声明
+        setattr(func, "_bolt_is_tool", True)  # noqa: B010
+        setattr(func, "_bolt_tool_name", tool_name)  # noqa: B010
+        setattr(func, "_bolt_tool_description", tool_desc)  # noqa: B010
+
+        return func
+
+    return decorator
+
+
+# ============ Agent 结果 ============
+
+
+class AgentResult(BaseModel):
+    """Agent 执行结果"""
+
+    success: bool = Field(default=True, description="是否成功")
+    output: str = Field(default="", description="输出内容")
+    error: str | None = Field(default=None, description="错误信息")
+    messages: list[ChatMessage] = Field(default_factory=list, description="消息历史")
+    tool_calls: list[dict[str, Any]] = Field(default_factory=list, description="工具调用记录")
+    token_usage: dict[str, int] = Field(default_factory=dict, description="Token 使用")
+
+
+# ============ Agent 基类 ============
+
+
+class BoltAgent(ABC):
+    """Agent 基类 - 由 OxyGent 引擎驱动。
+
+    用法:
+        class CommentAgent(BoltAgent):
+            def __init__(self):
+                super().__init__(
+                    name="comment_agent",
+                    model="gpt-4o",
+                    system_prompt="你是一个评论生成专家",
+                )
+
+            @tool(description="搜索相关笔记内容")
+            async def search_notes(self, query: str) -> str:
+                return await self.note_service.search(query)
+
+            async def run(self, note_url: str) -> AgentResult:
+                # invoke 内部由 OxyGent ReAct 循环驱动工具调用
+                comment = await self.invoke(f"为笔记生成评论: {note_url}")
+                return AgentResult(output=comment)
+    """
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        model: str | None = None,
+        provider: str | None = None,
+        system_prompt: str | None = None,
+        temperature: float = 0.7,
+        max_tokens: int = 4096,
+    ) -> None:
+        self.name = name
+        self.model = model or get_settings().llm_default_model or "gpt-4o"
+        self.provider = provider or get_settings().llm_default_provider or "openai"
+        self.system_prompt = system_prompt
+        self.temperature = temperature
+        self.max_tokens = max_tokens
+
+        # 工具注册表（OxyGent MAS 启动时桥接为 FunctionHub）
+        self._tools: dict[str, Tool] = {}
+        self._register_tools()
+
+        # 会话记忆缓存（session_id -> ConversationMemory）。
+        # 有界（LRU 语义）：对话型 Agent 的 session_id 是用户规模级的，
+        # 不设上限会随会话数慢性泄漏内存
+        self._memories: OrderedDict[str, ConversationMemory] = OrderedDict()
+        self._memories_maxsize = 1000
+
+        # 引擎句柄（懒创建）
+        self._engine: OxyEngine | None = None
+
+        # 登记到 OxyGent 运行时（纯同步登记；MAS 懒启动时物化）
+        from bolt.agent.oxy.runtime import get_oxy_runtime
+
+        get_oxy_runtime().register_agent(self)
+
+    def _register_tools(self) -> None:
+        """自动注册带 @tool 装饰器的方法（沿 MRO 收集，父类工具可继承）。
+
+        反向遍历 MRO 使子类对同名工具的覆盖优先生效。
+        """
+        seen: set[str] = set()
+        for klass in reversed(type(self).__mro__):
+            for attr_name, attr in klass.__dict__.items():
+                if not (callable(attr) and getattr(attr, "_bolt_is_tool", False)):
+                    continue
+                if attr._bolt_tool_name in seen:
+                    continue
+                seen.add(attr._bolt_tool_name)
+                self._tools[attr._bolt_tool_name] = Tool(
+                    name=attr._bolt_tool_name,
+                    description=attr._bolt_tool_description,
+                    func=getattr(self, attr_name),
+                )
+
+    def get_tools(self) -> list[Tool]:
+        """获取所有注册的工具"""
+        return list(self._tools.values())
+
+    @property
+    def has_tools(self) -> bool:
+        """是否注册了工具（决定 ReAct / Chat 映射与流式策略）"""
+        return bool(self._tools)
+
+    def get_memory(self, session_id: str = "default") -> ConversationMemory:
+        """获取（或创建）指定会话的记忆（同一 session_id 复用同一实例，LRU 淘汰最旧）。"""
+        if session_id not in self._memories:
+            self._memories[session_id] = get_memory_backend(session_id=session_id)
+        self._memories.move_to_end(session_id)
+        while len(self._memories) > self._memories_maxsize:
+            self._memories.popitem(last=False)
+        return self._memories[session_id]
+
+    # ============ OxyGent 引擎调用 ============
+
+    def _get_oxy_engine(self) -> OxyEngine:
+        from bolt.agent.oxy.engine import OxyEngine
+        from bolt.agent.oxy.runtime import get_oxy_runtime
+
+        if self._engine is None:
+            self._engine = OxyEngine(agent=self, runtime=get_oxy_runtime())
+        return self._engine
+
+    async def chat(
+        self,
+        messages: str | list[ChatMessage | dict[str, str]],
+        *,
+        use_tools: bool = True,
+        session_id: str | None = None,
+        timeout: float | None = None,
+    ) -> ChatMessage:
+        """调用 Agent 进行一轮对话。
+
+        Args:
+            messages: 单条消息或消息列表（ChatMessage / {"role","content"} dict）
+            use_tools: 是否允许工具调用（无工具 Agent 忽略）
+            session_id: 会话 ID；提供时启用会话记忆（多轮上下文）
+            timeout: 单轮超时秒数（None = 不限时）
+
+        Returns:
+            assistant 消息
+        """
+        return await self._get_oxy_engine().chat(messages, use_tools=use_tools, session_id=session_id, timeout=timeout)
+
+    async def invoke(
+        self,
+        message: str | list[ChatMessage | dict[str, str]],
+        *,
+        use_tools: bool = True,
+        session_id: str | None = None,
+        timeout: float | None = None,
+    ) -> str:
+        """简化调用 - 输入文本，返回文本。"""
+        return await self._get_oxy_engine().invoke(message, use_tools=use_tools, session_id=session_id, timeout=timeout)
+
+    async def stream(
+        self,
+        message: str | list[ChatMessage | dict[str, str]],
+        *,
+        use_tools: bool = True,
+        session_id: str | None = None,
+        timeout: float | None = None,
+    ) -> AsyncIterator[str]:
+        """流式输出文本块。
+
+        有工具的 Agent 采用缓冲策略（中间轮工具调用 JSON 不外漏，
+        最终以完整答案输出）；无工具 Agent 逐段透传。
+        """
+        async for chunk in self._get_oxy_engine().stream(
+            message, use_tools=use_tools, session_id=session_id, timeout=timeout
+        ):
+            yield chunk
+
+    # ============ 抽象方法 ============
+
+    @abstractmethod
+    async def run(self, *args: Any, **kwargs: Any) -> AgentResult:
+        """执行 Agent（子类实现）"""
+        pass
+
+    async def execute(self, *args: Any, **kwargs: Any) -> AgentResult:
+        """执行 Agent（带错误处理，不吞没不可恢复异常）"""
+        try:
+            result = await self.run(*args, **kwargs)
+            return result
+        except (KeyboardInterrupt, SystemExit):
+            raise
+        except Exception as e:
+            from bolt.core.logging import get_logger
+
+            get_logger(f"bolt.agent.{self.name}").exception("Agent execution failed", exc=e)
+            return AgentResult(
+                success=False,
+                error=str(e),
+            )
+
+
+def get_memory_backend(session_id: str) -> ConversationMemory:
+    """按 Settings 构建默认记忆后端。独立函数避免 base↔memory 模块级循环。
+
+    - ``memory``（默认）：进程内存储
+    - ``redis``：跨 worker 共享（复用 ``settings.redis_url`` 与 ``settings.memory_ttl``）
+    """
+    settings = get_settings()
+    backend = settings.memory_backend
+    if backend == "redis":
+        from bolt.agent.memory import RedisConversationMemory
+
+        return RedisConversationMemory(
+            session_id=session_id,
+            redis_url=settings.redis_url,
+            ttl=settings.memory_ttl,
+        )
+    from bolt.agent.memory import ConversationMemory
+
+    return ConversationMemory(session_id=session_id)

bolt/agent/example.py

@@ -0,0 +1,94 @@
+"""示例 Agent - 评论生成 Agent。
+
+演示如何使用 Bolt Agent 框架（OxyGent 引擎驱动）构建 AI Agent。
+"""
+
+from __future__ import annotations
+
+import logging
+
+from bolt.agent.base import AgentResult, BoltAgent, tool
+
+logger = logging.getLogger(__name__)
+
+
+class CommentAgent(BoltAgent):
+    """评论生成 Agent 示例。
+
+    用法:
+        agent = CommentAgent()
+
+        # 执行（invoke 内部由 OxyGent ReAct 循环驱动工具调用）
+        result = await agent.execute(note_url="https://xiaohongshu.com/note/123")
+        print(result.output)
+    """
+
+    def __init__(
+        self,
+        name: str = "comment_agent",
+        model: str = "gpt-4o",
+        provider: str = "openai",
+    ) -> None:
+        super().__init__(
+            name=name,
+            model=model,
+            provider=provider,
+            system_prompt="""你是一个专业的评论生成专家。
+你的任务是根据笔记内容生成有深度、有见解的评论。
+评论应该：
+1. 紧扣笔记主题
+2. 有独特的观点或见解
+3. 语言自然、有亲和力""",
+        )
+
+    @tool(description="搜索小红书笔记内容")
+    async def search_note(self, note_url: str) -> str:
+        """搜索小红书笔记内容。"""
+        # 这里应该调用实际的小红书 API
+        return "笔记内容摘要: 这是一篇关于美食探店的笔记..."
+
+    @tool(description="获取热门评论作为参考")
+    async def get_hot_comments(self, note_url: str, limit: int = 5) -> list[str]:
+        """获取热门评论。"""
+        return [
+            "这家店我也去过！真的很好吃！",
+            "感谢分享，已经收藏了~",
+        ]
+
+    async def run(self, note_url: str, style: str = "friendly") -> AgentResult:
+        """执行评论生成（工具调用由 ReAct 循环自动编排）。"""
+        prompt = f"""请为笔记 {note_url} 生成一条评论。
+
+步骤：
+1. 用工具搜索笔记内容
+2. 用工具获取热门评论参考
+3. 生成一条风格为「{style}」的评论，直接输出评论内容"""
+
+        response = await self.invoke(prompt)
+        return AgentResult(
+            success=True,
+            output=response,
+        )
+
+
+# ============ 使用示例 ============
+
+
+async def example_simple_agent() -> None:
+    """简单 Agent 示例"""
+    logger.info("简单 Agent 示例")
+
+    agent = CommentAgent()
+
+    # 检查工具注册
+    tools = agent.get_tools()
+    logger.info("注册的工具: %s", [t.name for t in tools])
+
+    result = await agent.execute(note_url="https://xiaohongshu.com/note/123")
+    logger.info("结果: %s", result)
+
+
+if __name__ == "__main__":
+    import asyncio
+
+    asyncio.run(example_simple_agent())