rootdriver 0.1.0__tar.gz → 0.3.0__tar.gz

rootdriver-0.3.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: rootdriver
+Version: 0.3.0
+Summary: Rooted in Origin, Driving All Things
+Author-email: zimvir <zimvir@qq.com>
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: openai>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+
+# RootDriver
+
+根源出发，驱动万物
+
+一个轻量级的 Python AI Agent 开发框架，支持单智能体和多智能体应用。
+
+## 特性
+
+- **简洁易用**：装饰器方式定义工具，快速构建 Agent
+- **模块化设计**：LLM 适配器、工具系统、会话管理解耦
+- **工具调用**：支持 function calling，自动执行工具并返回结果
+- **状态管理**：支持内存和数据库持久化检查点
+- **异常体系**：完整的异常类层次结构
+- **异步支持**：全面异步支持，并发多 Agent / 工具调用
+
+## 安装
+
+```bash
+pip install rootdriver
+```
+
+## 快速开始
+
+### 定义工具
+
+```python
+from rootdriver import tool
+
+@tool
+def get_weather(city: str) -> str:
+    """获取城市天气"""
+    return f"{city} 晴天"
+```
+
+### 创建 Agent
+
+```python
+from rootdriver import Agent, AgentLLM, OpenAIAdapter
+
+agent = Agent(
+    agent_llm=AgentLLM(
+        adapter=OpenAIAdapter(
+            api_key="YOUR_API_KEY",
+            base_url="BASE_URL"
+        ),
+        model="gpt-4",
+    ),
+    tools=[get_weather],
+    system_prompt="你是一个有用的助手",
+)
+
+# 单次对话
+response = agent.talk("北京天气怎么样？")
+print(response)
+```
+
+### 使用工具
+
+```python
+# 完整对话循环（包含工具调用）
+response = agent.react("帮我查下上海天气")
+print(response)
+```
+
+### 异步用法
+
+```python
+import asyncio
+from rootdriver import Agent, AgentLLM, OpenAIAdapter
+
+async def main():
+    agent = Agent(agent_llm=AgentLLM(...))
+
+    # 单次异步对话
+    response = await agent.atalk("你好")
+    print(response)
+
+    # 并发多个 Agent
+    results = await asyncio.gather(
+        agent.areact("问题1"),
+        agent.areact("问题2"),
+        agent.areact("问题3"),
+    )
+
+asyncio.run(main())
+```
+
+## 核心组件
+
+| 组件 | 说明 |
+|------|------|
+| `Agent` | 智能体入口，整合 LLM、工具、会话 |
+| `Engine` | 核心引擎，处理对话循环和工具调用 |
+| `Conversation` | 会话管理，维护消息历史 |
+| `LLM` | LLM 调用封装 |
+| `Tool` | 工具集合，管理所有可调用工具 |
+| `State` | 状态管理，支持检查点和持久化 |
+
+## 项目结构
+
+```
+rootdriver/
+├── agent.py           # Agent 智能体
+├── engine.py          # 引擎核心
+├── conversation.py    # 对话管理
+├── state.py           # 状态管理
+├── exception.py       # 异常定义
+├── llm/
+│   ├── llm.py         # LLM 封装
+│   ├── base_adapter.py    # 适配器基类
+│   └── adapter/
+│       └── openai_adapter.py  # OpenAI 适配器
+├── tool/
+│   ├── base_tool.py   # 工具基类
+│   └── tools.py       # 工具集
+├── types/             # 类型定义
+└── utils/             # 工具函数
+```
+
+## License
+
+MIT

rootdriver-0.3.0/README.md

@@ -0,0 +1,122 @@
+# RootDriver
+
+根源出发，驱动万物
+
+一个轻量级的 Python AI Agent 开发框架，支持单智能体和多智能体应用。
+
+## 特性
+
+- **简洁易用**：装饰器方式定义工具，快速构建 Agent
+- **模块化设计**：LLM 适配器、工具系统、会话管理解耦
+- **工具调用**：支持 function calling，自动执行工具并返回结果
+- **状态管理**：支持内存和数据库持久化检查点
+- **异常体系**：完整的异常类层次结构
+- **异步支持**：全面异步支持，并发多 Agent / 工具调用
+
+## 安装
+
+```bash
+pip install rootdriver
+```
+
+## 快速开始
+
+### 定义工具
+
+```python
+from rootdriver import tool
+
+@tool
+def get_weather(city: str) -> str:
+    """获取城市天气"""
+    return f"{city} 晴天"
+```
+
+### 创建 Agent
+
+```python
+from rootdriver import Agent, AgentLLM, OpenAIAdapter
+
+agent = Agent(
+    agent_llm=AgentLLM(
+        adapter=OpenAIAdapter(
+            api_key="YOUR_API_KEY",
+            base_url="BASE_URL"
+        ),
+        model="gpt-4",
+    ),
+    tools=[get_weather],
+    system_prompt="你是一个有用的助手",
+)
+
+# 单次对话
+response = agent.talk("北京天气怎么样？")
+print(response)
+```
+
+### 使用工具
+
+```python
+# 完整对话循环（包含工具调用）
+response = agent.react("帮我查下上海天气")
+print(response)
+```
+
+### 异步用法
+
+```python
+import asyncio
+from rootdriver import Agent, AgentLLM, OpenAIAdapter
+
+async def main():
+    agent = Agent(agent_llm=AgentLLM(...))
+
+    # 单次异步对话
+    response = await agent.atalk("你好")
+    print(response)
+
+    # 并发多个 Agent
+    results = await asyncio.gather(
+        agent.areact("问题1"),
+        agent.areact("问题2"),
+        agent.areact("问题3"),
+    )
+
+asyncio.run(main())
+```
+
+## 核心组件
+
+| 组件 | 说明 |
+|------|------|
+| `Agent` | 智能体入口，整合 LLM、工具、会话 |
+| `Engine` | 核心引擎，处理对话循环和工具调用 |
+| `Conversation` | 会话管理，维护消息历史 |
+| `LLM` | LLM 调用封装 |
+| `Tool` | 工具集合，管理所有可调用工具 |
+| `State` | 状态管理，支持检查点和持久化 |
+
+## 项目结构
+
+```
+rootdriver/
+├── agent.py           # Agent 智能体
+├── engine.py          # 引擎核心
+├── conversation.py    # 对话管理
+├── state.py           # 状态管理
+├── exception.py       # 异常定义
+├── llm/
+│   ├── llm.py         # LLM 封装
+│   ├── base_adapter.py    # 适配器基类
+│   └── adapter/
+│       └── openai_adapter.py  # OpenAI 适配器
+├── tool/
+│   ├── base_tool.py   # 工具基类
+│   └── tools.py       # 工具集
+├── types/             # 类型定义
+└── utils/             # 工具函数
+```
+
+## License
+
+MIT

{rootdriver-0.1.0 → rootdriver-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rootdriver"
-version = "0.1.0"
+version = "0.3.0"
 description = "Rooted in Origin, Driving All Things"
 readme = "README.md"
 license = {text = "MIT"}
@@ -22,5 +22,8 @@ dev = [
     "pytest>=7.0.0",
 ]
 
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
 [tool.setuptools]
 packages = ["rootdriver"]

rootdriver-0.3.0/rootdriver/__init__.py

@@ -0,0 +1,58 @@
+__version__ = "0.3.0"
+__author__ = "zimvir"
+__email__ = "zimvir@qq.com"
+
+from .agent import Agent
+from .engine import Engine
+from .conversation import Conversation
+from .state import State
+from .llm import LLM
+from .llm.base_adapter import BaseAdapter
+from .llm.adapter import OpenAIAdapter
+from .tool import tool, Tool
+from .types.agent import AgentLLM
+from .types import Message, ToolDefinition, ToolCall
+from .exception import (
+    LLMError,
+    LLMInvokeError,
+    LLMResponseError,
+    ToolError,
+    ToolNotFoundError,
+    ToolInvokeError,
+    ToolArgumentError,
+    AgentError,
+    ConversationError,
+    StateError,
+    CheckpointNotFoundError,
+    StateSaveError,
+    StateLoadError,
+)
+
+__all__ = [
+    "Agent",
+    "Engine",
+    "Conversation",
+    "State",
+    "LLM",
+    "BaseAdapter",
+    "OpenAIAdapter",
+    "tool",
+    "Tool",
+    "AgentLLM",
+    "Message",
+    "ToolDefinition",
+    "ToolCall",
+    "LLMError",
+    "LLMInvokeError",
+    "LLMResponseError",
+    "ToolError",
+    "ToolNotFoundError",
+    "ToolInvokeError",
+    "ToolArgumentError",
+    "AgentError",
+    "ConversationError",
+    "StateError",
+    "CheckpointNotFoundError",
+    "StateSaveError",
+    "StateLoadError",
+]

{rootdriver-0.1.0 → rootdriver-0.3.0}/rootdriver/agent.py

@@ -1,12 +1,12 @@
 from pathlib import Path
 from uuid import uuid4
-
+import asyncio
 from .engine import Engine
 from .llm import LLM
 from .conversation import Conversation
 from .tool import Tool, BaseTool
 from .types.agent import AgentLLM
-from .types import ToolDefinition
+from .state import State
 from .utils import build_system_message, build_message, build_tool_message, build_user_message, build_assistant_message
 
 class Agent:
@@ -14,18 +14,20 @@ class Agent:
     def __init__(
         self,
         agent_llm: AgentLLM,
-        *,
+        id: str | None = None,
         tools: list[BaseTool] | None = None,
         system_prompt: str | None = None,
-        id: str | None = None,
-        # save_path: str | Path | None = None,
-        # max_retries: int = 3,
-        timeout: float | None = None,
+
+        db_path: str| None = None,
+        # llm_retry: int = 3,
+        # timeout: float | None = None,
     ):
+        self.id = id if id else uuid4().hex
+        self.db_path = db_path
+
         self.conversation = Conversation(system_prompt)
         self.tool = Tool(tools if tools else [])
-        self.id = id if id else uuid4().hex
-        # self.save_path = save_path
+        self.state = State(self, self.db_path)
 
         self.engine = Engine(
             model=agent_llm.model,
@@ -45,4 +47,15 @@ class Agent:
         return self.engine.invoke(build_user_message(input_prompt)).content
 
 
+    """==========异步部分=========="""
+    async def areact(self, input_prompt:str) -> "str":
+        """一次 react 异步循环"""
+        response = await self.engine.arun(build_user_message(input_prompt))
+        return response.content
+
+    async def atalk(self, input_prompt:str) -> "str":
+        """一次 agent 异步调用"""
+        return await self.engine.ainvoke(build_user_message(input_prompt)).content
+
+
 

{rootdriver-0.1.0 → rootdriver-0.3.0}/rootdriver/conversation.py

@@ -40,6 +40,9 @@ class Conversation:
     def append_system(self, content: str) -> "Conversation":
         self.messages.append(Message(role="system", content=content, created_at=get_iso_timestamp()))
         return self
+    def update_message(self, messages: list[Message]) -> "Conversation":
+        self.messages = messages.copy()
+        return self
 
     def delete(self, index: int=-1) -> "Conversation":
         self.messages.pop(index)
@@ -53,18 +56,18 @@ class Conversation:
         '''返回 字典加列表组成的message（可转成json用于网络、跨语言传输） 组成的列表'''
         return [m.model_dump(exclude_none=True) for m in self.messages]
 
-
     @classmethod
     def from_dict_list(cls, messages: list[dict]) -> "Conversation":
         conv = cls()
         conv.messages = [Message.model_validate(m) for m in messages]
         return conv
-
+    from_messages_to_conversation = from_dict_list
     @classmethod
     def from_list(cls, messages: list[Message]) -> "Conversation":
         conv = cls()
         conv.messages = list(messages)
         return conv
+    from_messages_list_to_conversation = from_dict_list
 
     def clear(self) -> "Conversation":
         self.messages = []

{rootdriver-0.1.0 → rootdriver-0.3.0}/rootdriver/engine.py

@@ -1,4 +1,4 @@
-
+import asyncio
 
 from .llm import LLM
 from .conversation import Conversation
@@ -14,18 +14,16 @@ class Engine:
         self.model = model
 
     def invoke(self, input_message:Message) -> Message:
+        """但系调用llm，并存入记忆，无tool调用"""
         self.conversation.append(input_message)
         message = self.chat()
         return message
 
     def chat(self) -> Message:
         """
-
         1. 读会话消息
         2. 大模型交流
         3. 追加会话消息
-        4. 判断 是否调用工具
-        5. 是： tool 返回结果并追加，否： 追加并返回
         """
         # 1. 读会话消息
         message = self.conversation.get_messages()
@@ -41,17 +39,9 @@ class Engine:
 
     def deal_tool_or_output(self, response_message:Message) -> Message|None:
         """
-                1. 追加输入
-                2. 读会话消息
-                3. 大模型交流
-                4. 追加会话消息
-                5. 判断 是否调用工具
-                6. 是： tool 返回结果并追加，否： 追加并返回
-
-
-                Returns:
-
-                """
+        5. 判断 是否调用工具
+        6. 是： tool 返回结果并追加，否： 追加并返回
+        """
 
         # 5. 判断 是否调用工具
         if response_message.tool_calls:
@@ -106,3 +96,68 @@ class Engine:
         """把 LLM 响应转成 Message 。"""
         return response.message
 
+    """==========异步部分=========="""
+    async def ainvoke(self, input_message:Message) -> Message:
+        """但系调用llm，并存入记忆，无tool调用"""
+        self.conversation.append(input_message)
+        message = await self.achat()
+        return message
+
+
+    async def achat(self) -> Message:
+        """
+        1. 读会话消息
+        2. 大模型交流
+        3. 追加会话消息
+        """
+        # 1. 读会话消息
+        message = self.conversation.get_messages()
+
+        # 2. llm交互
+        response = await self.llm.ainvoke(self.messages_to_llm_request(message))
+
+        # 3. 追加会话消息
+        response_message = self.llm_response_to_message(response)
+        self.conversation.append(response_message)
+
+        return response_message
+
+    async def adeal_tool_or_output(self, response_message:Message) -> Message|None:
+        """
+        5. 判断 是否调用工具
+        6. 是： tool 返回结果并追加，否： 追加并返回
+        """
+
+        # 5. 判断 是否调用工具
+        if response_message.tool_calls:
+            # 6. 是： tool 返回结果追加
+            tool_results = await self.tool.ainvoke_many(response_message.tool_calls)
+            self.conversation.append_many([build_tool_message(tool_result.tool_call_id, tool_result.content) for tool_result in tool_results])
+            return None
+        else:
+            # 6. 否： 追加并返回
+            return response_message
+
+
+    async def arun(self, input_message:Message) ->Message:
+        """
+        1. 追加输入
+        2. 读会话消息
+        3. 大模型交流
+        4. 追加会话消息
+        5. 判断 是否调用工具
+        6. 是： tool 返回结果并追加，否： 追加并返回
+
+
+        Returns:
+
+        """
+        self.conversation.append(input_message)
+        while True:
+
+            response_message = await self.achat()
+            result = await self.adeal_tool_or_output(response_message)
+            if result is None:
+                continue
+            elif isinstance(result, Message):
+                return result

rootdriver-0.3.0/rootdriver/exception.py

@@ -0,0 +1,119 @@
+"""RootDriver 异常体系。"""
+
+
+# ============== LLM 相关 ==============
+
+class LLMError(Exception):
+    """LLM 调用基类。"""
+
+    def __init__(self, message: str, model: str = None, **kwargs):
+        self.model = model
+        super().__init__(message)
+
+
+class LLMInvokeError(LLMError):
+    """LLM 调用失败（网络错误、API 错误、超时等）。"""
+
+    def __init__(self, message: str, model: str = None, status_code: int = None, **kwargs):
+        self.status_code = status_code
+        super().__init__(message, model)
+
+
+class LLMResponseError(LLMError):
+    """LLM 返回格式异常（解析失败、缺少字段等）。"""
+
+    pass
+
+
+class AdapterError(Exception):
+    """适配器基类。"""
+
+    pass
+
+
+# ============== 工具相关 ==============
+
+class ToolError(Exception):
+    """工具基类。"""
+
+    pass
+
+
+class ToolNotFoundError(ToolError):
+    """工具不存在。"""
+
+    def __init__(self, name: str, available: list = None):
+        self.name = name
+        self.available = available or []
+        msg = f"Tool '{name}' not found"
+        if available:
+            msg += f", available: {available}"
+        super().__init__(msg)
+
+
+class ToolInvokeError(ToolError):
+    """工具执行失败。"""
+
+    def __init__(self, name: str, reason: str = None):
+        self.name = name
+        self.reason = reason
+        msg = f"Tool '{name}' invoke failed"
+        if reason:
+            msg += f": {reason}"
+        super().__init__(msg)
+
+
+class ToolArgumentError(ToolError):
+    """工具参数错误。"""
+
+    def __init__(self, name: str, missing: list = None, invalid: dict = None):
+        self.name = name
+        self.missing = missing or []
+        self.invalid = invalid or {}
+        msg = f"Tool '{name}' argument error"
+        if missing:
+            msg += f", missing: {missing}"
+        super().__init__(msg)
+
+
+# ============== Agent / 会话相关 ==============
+
+class AgentError(Exception):
+    """Agent 基类。"""
+
+    pass
+
+
+class ConversationError(Exception):
+    """会话操作错误。"""
+
+    pass
+
+
+# ============== State 相关 ==============
+
+class StateError(Exception):
+    """State 基类。"""
+
+    pass
+
+
+class CheckpointNotFoundError(StateError):
+    """检查点不存在。"""
+
+    def __init__(self, name: str, source: str = "memory"):
+        self.name = name
+        self.source = source
+        super().__init__(f"Checkpoint '{name}' not found in {source}")
+
+
+class StateSaveError(StateError):
+    """状态保存失败。"""
+
+    pass
+
+
+class StateLoadError(StateError):
+    """状态加载失败。"""
+
+    pass

rootdriver-0.3.0/rootdriver/state.py

@@ -0,0 +1,103 @@
+
+
+from __future__ import annotations
+
+from .conversation import Conversation
+from .exception import CheckpointNotFoundError
+import json
+
+class State:
+    def __init__(self, agent_obj:Agent, db_path):
+        self.agent = agent_obj
+        self.db_path = db_path
+        self.checkpoints:dict[str,Conversation] =  {}
+
+    def checkpoint(self, name) -> "State":
+        self.checkpoints[name] = self.agent.conversation.copy()
+        return self
+    def save_messages(self, name:str, agent_id, messages:list[dict]) -> Agent:
+        """
+        Args:
+            name: 检查点 的名称
+            agent_id: agent的id， 默认当前agent的id
+        """
+        # 打开数据库
+        data = json.load(self.db_path)
+        # 确保有此agent
+        if data.get(agent_id) is None:
+            data[agent_id] = {}
+        data[agent_id][name] = messages
+        json.dump(data, self.db_path)
+        return self.agent
+    def save_from_now(self, name:str, agent_id:str|None=None) -> Agent:
+        """
+        Args:
+            name: 检查点 的名称
+            agent_id: agent的id， 默认当前agent的id
+        """
+        self.save_messages(name, agent_id, self.agent.conversation.get_messages_in_list())
+        return self.agent
+    def save_from_checkpoints(self, name:str,checkpoint_name:str, agent_id:str|None=None) -> Agent:
+        """
+        Args:
+            name: 检查点 的名称
+            checkpoint_name : 再checkpoints中的name
+            agent_id: agent的id， 默认当前agent的id
+        """
+        checkpoint = self.checkpoints.get(checkpoint_name)
+        if checkpoint is None:
+            raise CheckpointNotFoundError(checkpoint_name, "memory")
+        messages = checkpoint.get_messages_in_list()
+        self.save_messages(name, agent_id, messages)
+        return self.agent
+
+    def get_from_checkpoints(self, name) -> Conversation:
+        """
+        Args:
+            name: 检查点 的名称
+            agent_id: agent的id， 默认当前agent的id
+        Return:
+            Conversation
+        """
+
+        checkpoint:Conversation = self.checkpoints.get(name, None)
+        if checkpoint is None:
+            raise CheckpointNotFoundError(name, "memory")
+        return checkpoint
+    def get_from_db(self, name, agent_id:str|None=None) -> Conversation:
+        """
+        Args:
+            name: 检查点 的名称
+            agent_id: agent的id， 默认当前agent的id
+        Return:
+            Conversation
+        """
+        if agent_id is None:
+            agent_id = self.agent.id
+
+        data = json.load(self.db_path)
+
+        if data.get(agent_id) is None:
+            raise CheckpointNotFoundError(name, f"db (unknown agent_id: {agent_id})")
+
+        messages = data[agent_id].get(name, None)
+        if messages is None:
+            raise CheckpointNotFoundError(name, f"db ({self.db_path})")
+
+        return Conversation.from_messages_list_to_conversation(messages)
+
+    def load_from_checkpoint(self, name:str|None=None) -> Agent:
+        messages = self.get_from_checkpoints(name).messages
+        self.agent.conversation.update_message(messages)
+        return self.agent
+
+    def load_from_db(self, name:str|None=None, agent_id:str|None =None ) -> Agent:
+        """
+        Args:
+            name: 检查点 的名称
+            agent_id: agent的id， 默认当前agent的id
+        """
+        agent_id = agent_id if agent_id is not None else self.agent.id
+        messages = self.get_from_db(name, agent_id).messages
+        self.agent.conversation.update_message(messages)
+        return self.agent

rootdriver-0.3.0/rootdriver.egg-info/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: rootdriver
+Version: 0.3.0
+Summary: Rooted in Origin, Driving All Things
+Author-email: zimvir <zimvir@qq.com>
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: openai>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+
+# RootDriver
+
+根源出发，驱动万物
+
+一个轻量级的 Python AI Agent 开发框架，支持单智能体和多智能体应用。
+
+## 特性
+
+- **简洁易用**：装饰器方式定义工具，快速构建 Agent
+- **模块化设计**：LLM 适配器、工具系统、会话管理解耦
+- **工具调用**：支持 function calling，自动执行工具并返回结果
+- **状态管理**：支持内存和数据库持久化检查点
+- **异常体系**：完整的异常类层次结构
+- **异步支持**：全面异步支持，并发多 Agent / 工具调用
+
+## 安装
+
+```bash
+pip install rootdriver
+```
+
+## 快速开始
+
+### 定义工具
+
+```python
+from rootdriver import tool
+
+@tool
+def get_weather(city: str) -> str:
+    """获取城市天气"""
+    return f"{city} 晴天"
+```
+
+### 创建 Agent
+
+```python
+from rootdriver import Agent, AgentLLM, OpenAIAdapter
+
+agent = Agent(
+    agent_llm=AgentLLM(
+        adapter=OpenAIAdapter(
+            api_key="YOUR_API_KEY",
+            base_url="BASE_URL"
+        ),
+        model="gpt-4",
+    ),
+    tools=[get_weather],
+    system_prompt="你是一个有用的助手",
+)
+
+# 单次对话
+response = agent.talk("北京天气怎么样？")
+print(response)
+```
+
+### 使用工具
+
+```python
+# 完整对话循环（包含工具调用）
+response = agent.react("帮我查下上海天气")
+print(response)
+```
+
+### 异步用法
+
+```python
+import asyncio
+from rootdriver import Agent, AgentLLM, OpenAIAdapter
+
+async def main():
+    agent = Agent(agent_llm=AgentLLM(...))
+
+    # 单次异步对话
+    response = await agent.atalk("你好")
+    print(response)
+
+    # 并发多个 Agent
+    results = await asyncio.gather(
+        agent.areact("问题1"),
+        agent.areact("问题2"),
+        agent.areact("问题3"),
+    )
+
+asyncio.run(main())
+```
+
+## 核心组件
+
+| 组件 | 说明 |
+|------|------|
+| `Agent` | 智能体入口，整合 LLM、工具、会话 |
+| `Engine` | 核心引擎，处理对话循环和工具调用 |
+| `Conversation` | 会话管理，维护消息历史 |
+| `LLM` | LLM 调用封装 |
+| `Tool` | 工具集合，管理所有可调用工具 |
+| `State` | 状态管理，支持检查点和持久化 |
+
+## 项目结构
+
+```
+rootdriver/
+├── agent.py           # Agent 智能体
+├── engine.py          # 引擎核心
+├── conversation.py    # 对话管理
+├── state.py           # 状态管理
+├── exception.py       # 异常定义
+├── llm/
+│   ├── llm.py         # LLM 封装
+│   ├── base_adapter.py    # 适配器基类
+│   └── adapter/
+│       └── openai_adapter.py  # OpenAI 适配器
+├── tool/
+│   ├── base_tool.py   # 工具基类
+│   └── tools.py       # 工具集
+├── types/             # 类型定义
+└── utils/             # 工具函数
+```
+
+## License
+
+MIT

{rootdriver-0.1.0 → rootdriver-0.3.0}/rootdriver.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ rootdriver/constants.py
 rootdriver/conversation.py
 rootdriver/engine.py
 rootdriver/exception.py
+rootdriver/state.py
 rootdriver.egg-info/PKG-INFO
 rootdriver.egg-info/SOURCES.txt
 rootdriver.egg-info/dependency_links.txt
@@ -13,4 +14,5 @@ rootdriver.egg-info/requires.txt
 rootdriver.egg-info/top_level.txt
 tests/test_base_tool.py
 tests/test_conversation.py
-tests/test_tool.py
+tests/test_tool.py
+tests/test_tool_async.py

{rootdriver-0.1.0 → rootdriver-0.3.0}/tests/test_tool.py

@@ -2,6 +2,7 @@ import pytest
 from rootdriver.tool.base_tool import BaseTool
 from rootdriver.tool.tools import Tool
 from rootdriver.types.tool import ToolCall
+from rootdriver.exception import ToolNotFoundError
 
 
 def get_weather(city: str) -> str:
@@ -52,9 +53,10 @@ def test_tool_invoke_success(tool_registry):
 
 
 def test_tool_invoke_not_found(tool_registry):
-    result = tool_registry.invoke(ToolCall(id="2", name="not_exist", arguments={}))
-    assert result.tool_call_id == "2"
-    assert "not found" in result.content
+    with pytest.raises(ToolNotFoundError) as exc_info:
+        tool_registry.invoke(ToolCall(id="2", name="not_exist", arguments={}))
+    assert exc_info.value.name == "not_exist"
+    assert "get_weather" in str(exc_info.value.available)
 
 
 def test_tool_invoke_many(tool_registry):

rootdriver-0.3.0/tests/test_tool_async.py

@@ -0,0 +1,60 @@
+import asyncio
+import time
+import sys
+sys.path.insert(0, "..")
+
+import pytest
+from rootdriver.tool import BaseTool, tool
+
+@tool
+def sync_weather(city: str) -> str:
+    """同步查天气"""
+    time.sleep(0.5)
+    return f"{city}: 晴天"
+
+@tool
+async def async_weather(city: str) -> str:
+    """异步查天气"""
+    await asyncio.sleep(0.5)
+    return f"{city}: 多云"
+
+@pytest.mark.asyncio
+async def test_base_tool_ainvoke():
+    """测试 BaseTool.ainvoke"""
+    result = await sync_weather.ainvoke({"city": "北京"})
+    assert "北京" in result and "晴天" in result
+
+    result = await async_weather.ainvoke({"city": "北京"})
+    assert "北京" in result and "多云" in result
+
+@pytest.mark.asyncio
+async def test_concurrent():
+    """测试并发执行"""
+    start = time.time()
+    results = await asyncio.gather(
+        sync_weather.ainvoke({"city": "北京"}),
+        sync_weather.ainvoke({"city": "上海"}),
+        async_weather.ainvoke({"city": "广州"}),
+    )
+    elapsed = time.time() - start
+
+    assert elapsed < 0.8, f"应该并发执行，但耗时 {elapsed} 秒"
+    assert len(results) == 3
+
+@pytest.mark.asyncio
+async def test_ainvoke_many():
+    """测试批量异步调用"""
+    from rootdriver.types.tool import ToolCall
+    from rootdriver.tool import Tool
+
+    tool_calls = [
+        ToolCall(id="1", name="sync_weather", arguments={"city": "北京"}),
+        ToolCall(id="2", name="async_weather", arguments={"city": "上海"}),
+    ]
+
+    tool_set = Tool([sync_weather, async_weather])
+    results = await tool_set.ainvoke_many(tool_calls)
+
+    assert len(results) == 2
+    assert "北京" in results[0].content
+    assert "上海" in results[1].content

rootdriver-0.1.0/PKG-INFO

@@ -1,102 +0,0 @@
-Metadata-Version: 2.4
-Name: rootdriver
-Version: 0.1.0
-Summary: Rooted in Origin, Driving All Things
-Author-email: zimvir <zimvir@qq.com>
-License: MIT
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-Requires-Dist: openai>=1.0.0
-Requires-Dist: pydantic>=2.0.0
-Provides-Extra: dev
-Requires-Dist: pytest>=7.0.0; extra == "dev"
-
-# RootDriver
-
-根源出发， 驱动万物
-
-一个轻量级的 Python AI Agent 开发框架。
-
-## 特性
-
-- **简洁易用**：装饰器方式定义工具，快速构建 Agent
-- **模块化设计**：LLM 适配器、工具系统、会话管理解耦
-- **工具调用**：支持 function calling，自动执行工具并返回结果
-- **多适配器**：基于适配器模式，方便扩展其他 LLM Provider
-
-## 安装
-
-```bash
-pip install rootdriver
-```
-
-## 快速开始
-
-### 定义工具
-
-```python
-from rootdriver import tool
-
-@tool
-def get_weather(city: str) -> str:
-    """获取城市天气"""
-    return f"{city} 晴天"
-```
-
-### 创建 Agent
-
-```python
-from rootdriver import Agent, AgentLLM, OpenAIAdapter
-agent_llm=AgentLLM(
-    adapter=OpenAIAdapter(
-        api_key="YOUR_API_KEY",
-        base_url="BASE_URL"
-    ),
-    model="gpt-4",
-        
-    ),
-agent = Agent(
-    agent_llm=agent_llm,
-    tools=[get_weather],
-    system_prompt="你是一个有用的助手",
-)
-
-# 单次对话
-response = agent.talk("北京天气怎么样？")
-print(response)
-```
-
-### 使用工具
-
-```python
-# 完整对话循环（包含工具调用）
-response = Agent.react("帮我查下上海天气")
-print(response)
-```
-
-## 核心组件
-
-| 组件 | 说明 |
-|------|------|
-| `Agent` | 智能体入口，整合 LLM、工具、会话 |
-| `Engine` | 核心引擎，处理对话循环和工具调用 |
-| `Conversation` | 会话管理，维护消息历史 |
-| `LLM` | LLM 调用封装 |
-| `Tool` | 工具集合，管理所有可调用工具 |
-
-## 项目结构
-
-```
-rootdriver/
-├── agent.py          # Agent 智能体
-├── engine.py         # 引擎核心
-├── conversation.py   # 对话管理
-├── llm/              # LLM 适配器
-├── tool/             # 工具系统
-├── types/            # 类型定义
-└── utils/            # 工具函数
-```
-
-## License
-
-MIT

rootdriver-0.1.0/README.md

@@ -1,89 +0,0 @@
-# RootDriver
-
-根源出发， 驱动万物
-
-一个轻量级的 Python AI Agent 开发框架。
-
-## 特性
-
-- **简洁易用**：装饰器方式定义工具，快速构建 Agent
-- **模块化设计**：LLM 适配器、工具系统、会话管理解耦
-- **工具调用**：支持 function calling，自动执行工具并返回结果
-- **多适配器**：基于适配器模式，方便扩展其他 LLM Provider
-
-## 安装
-
-```bash
-pip install rootdriver
-```
-
-## 快速开始
-
-### 定义工具
-
-```python
-from rootdriver import tool
-
-@tool
-def get_weather(city: str) -> str:
-    """获取城市天气"""
-    return f"{city} 晴天"
-```
-
-### 创建 Agent
-
-```python
-from rootdriver import Agent, AgentLLM, OpenAIAdapter
-agent_llm=AgentLLM(
-    adapter=OpenAIAdapter(
-        api_key="YOUR_API_KEY",
-        base_url="BASE_URL"
-    ),
-    model="gpt-4",
-        
-    ),
-agent = Agent(
-    agent_llm=agent_llm,
-    tools=[get_weather],
-    system_prompt="你是一个有用的助手",
-)
-
-# 单次对话
-response = agent.talk("北京天气怎么样？")
-print(response)
-```
-
-### 使用工具
-
-```python
-# 完整对话循环（包含工具调用）
-response = Agent.react("帮我查下上海天气")
-print(response)
-```
-
-## 核心组件
-
-| 组件 | 说明 |
-|------|------|
-| `Agent` | 智能体入口，整合 LLM、工具、会话 |
-| `Engine` | 核心引擎，处理对话循环和工具调用 |
-| `Conversation` | 会话管理，维护消息历史 |
-| `LLM` | LLM 调用封装 |
-| `Tool` | 工具集合，管理所有可调用工具 |
-
-## 项目结构
-
-```
-rootdriver/
-├── agent.py          # Agent 智能体
-├── engine.py         # 引擎核心
-├── conversation.py   # 对话管理
-├── llm/              # LLM 适配器
-├── tool/             # 工具系统
-├── types/            # 类型定义
-└── utils/            # 工具函数
-```
-
-## License
-
-MIT

rootdriver-0.1.0/rootdriver/__init__.py

@@ -1,32 +0,0 @@
-__version__ = "0.1.0"
-__author__ = "zimvir"
-__email__ = "zimvir@qq.com"
-
-
-
-
-
-from .agent import Agent
-from .engine import Engine
-from .conversation import Conversation
-from .llm import LLM
-from .llm.base_adapter import BaseAdapter
-from .llm.adapter import OpenAIAdapter
-from .tool import tool, Tool
-from .types.agent import AgentLLM
-from .types import Message, ToolDefinition, ToolCall
-
-__all__ = [
-    "Agent",
-    "Engine",
-    "Conversation",
-    "LLM",
-    "BaseAdapter",
-    "OpenAIAdapter",
-    "tool",
-    "Tool",
-    "AgentLLM",
-    "Message",
-    "ToolDefinition",
-    "ToolCall",
-]

rootdriver-0.1.0/rootdriver/exception.py

@@ -1 +0,0 @@
-

rootdriver-0.1.0/rootdriver.egg-info/PKG-INFO

@@ -1,102 +0,0 @@
-Metadata-Version: 2.4
-Name: rootdriver
-Version: 0.1.0
-Summary: Rooted in Origin, Driving All Things
-Author-email: zimvir <zimvir@qq.com>
-License: MIT
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-Requires-Dist: openai>=1.0.0
-Requires-Dist: pydantic>=2.0.0
-Provides-Extra: dev
-Requires-Dist: pytest>=7.0.0; extra == "dev"
-
-# RootDriver
-
-根源出发， 驱动万物
-
-一个轻量级的 Python AI Agent 开发框架。
-
-## 特性
-
-- **简洁易用**：装饰器方式定义工具，快速构建 Agent
-- **模块化设计**：LLM 适配器、工具系统、会话管理解耦
-- **工具调用**：支持 function calling，自动执行工具并返回结果
-- **多适配器**：基于适配器模式，方便扩展其他 LLM Provider
-
-## 安装
-
-```bash
-pip install rootdriver
-```
-
-## 快速开始
-
-### 定义工具
-
-```python
-from rootdriver import tool
-
-@tool
-def get_weather(city: str) -> str:
-    """获取城市天气"""
-    return f"{city} 晴天"
-```
-
-### 创建 Agent
-
-```python
-from rootdriver import Agent, AgentLLM, OpenAIAdapter
-agent_llm=AgentLLM(
-    adapter=OpenAIAdapter(
-        api_key="YOUR_API_KEY",
-        base_url="BASE_URL"
-    ),
-    model="gpt-4",
-        
-    ),
-agent = Agent(
-    agent_llm=agent_llm,
-    tools=[get_weather],
-    system_prompt="你是一个有用的助手",
-)
-
-# 单次对话
-response = agent.talk("北京天气怎么样？")
-print(response)
-```
-
-### 使用工具
-
-```python
-# 完整对话循环（包含工具调用）
-response = Agent.react("帮我查下上海天气")
-print(response)
-```
-
-## 核心组件
-
-| 组件 | 说明 |
-|------|------|
-| `Agent` | 智能体入口，整合 LLM、工具、会话 |
-| `Engine` | 核心引擎，处理对话循环和工具调用 |
-| `Conversation` | 会话管理，维护消息历史 |
-| `LLM` | LLM 调用封装 |
-| `Tool` | 工具集合，管理所有可调用工具 |
-
-## 项目结构
-
-```
-rootdriver/
-├── agent.py          # Agent 智能体
-├── engine.py         # 引擎核心
-├── conversation.py   # 对话管理
-├── llm/              # LLM 适配器
-├── tool/             # 工具系统
-├── types/            # 类型定义
-└── utils/            # 工具函数
-```
-
-## License
-
-MIT