rootdriver 0.1.0__tar.gz → 0.2.0__tar.gz

{rootdriver-0.1.0 → rootdriver-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rootdriver
-Version: 0.1.0
+Version: 0.2.0
 Summary: Rooted in Origin, Driving All Things
 Author-email: zimvir <zimvir@qq.com>
 License: MIT
@@ -13,16 +13,17 @@ Requires-Dist: pytest>=7.0.0; extra == "dev"
 
 # RootDriver
 
-根源出发， 驱动万物
+根源出发，驱动万物
 
-一个轻量级的 Python AI Agent 开发框架。
+一个轻量级的 Python AI Agent 开发框架，支持单智能体和多智能体应用。
 
 ## 特性
 
 - **简洁易用**：装饰器方式定义工具，快速构建 Agent
 - **模块化设计**：LLM 适配器、工具系统、会话管理解耦
 - **工具调用**：支持 function calling，自动执行工具并返回结果
-- **多适配器**：基于适配器模式，方便扩展其他 LLM Provider
+- **状态管理**：支持内存和数据库持久化检查点
+- **异常体系**：完整的异常类层次结构
 
 ## 安装
 
@@ -47,16 +48,15 @@ def get_weather(city: str) -> str:
 
 ```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,
+    agent_llm=AgentLLM(
+        adapter=OpenAIAdapter(
+            api_key="YOUR_API_KEY",
+            base_url="BASE_URL"
+        ),
+        model="gpt-4",
+    ),
     tools=[get_weather],
     system_prompt="你是一个有用的助手",
 )
@@ -70,7 +70,7 @@ print(response)
 
 ```python
 # 完整对话循环（包含工具调用）
-response = Agent.react("帮我查下上海天气")
+response = agent.react("帮我查下上海天气")
 print(response)
 ```
 
@@ -83,18 +83,27 @@ print(response)
 | `Conversation` | 会话管理，维护消息历史 |
 | `LLM` | LLM 调用封装 |
 | `Tool` | 工具集合，管理所有可调用工具 |
+| `State` | 状态管理，支持检查点和持久化 |
 
 ## 项目结构
 
 ```
 rootdriver/
-├── agent.py          # Agent 智能体
-├── engine.py         # 引擎核心
-├── conversation.py   # 对话管理
-├── llm/              # LLM 适配器
-├── tool/             # 工具系统
-├── types/            # 类型定义
-└── utils/            # 工具函数
+├── 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

{rootdriver-0.1.0 → rootdriver-0.2.0}/README.md

@@ -1,15 +1,16 @@
 # RootDriver
 
-根源出发， 驱动万物
+根源出发，驱动万物
 
-一个轻量级的 Python AI Agent 开发框架。
+一个轻量级的 Python AI Agent 开发框架，支持单智能体和多智能体应用。
 
 ## 特性
 
 - **简洁易用**：装饰器方式定义工具，快速构建 Agent
 - **模块化设计**：LLM 适配器、工具系统、会话管理解耦
 - **工具调用**：支持 function calling，自动执行工具并返回结果
-- **多适配器**：基于适配器模式，方便扩展其他 LLM Provider
+- **状态管理**：支持内存和数据库持久化检查点
+- **异常体系**：完整的异常类层次结构
 
 ## 安装
 
@@ -34,16 +35,15 @@ def get_weather(city: str) -> str:
 
 ```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,
+    agent_llm=AgentLLM(
+        adapter=OpenAIAdapter(
+            api_key="YOUR_API_KEY",
+            base_url="BASE_URL"
+        ),
+        model="gpt-4",
+    ),
     tools=[get_weather],
     system_prompt="你是一个有用的助手",
 )
@@ -57,7 +57,7 @@ print(response)
 
 ```python
 # 完整对话循环（包含工具调用）
-response = Agent.react("帮我查下上海天气")
+response = agent.react("帮我查下上海天气")
 print(response)
 ```
 
@@ -70,18 +70,27 @@ print(response)
 | `Conversation` | 会话管理，维护消息历史 |
 | `LLM` | LLM 调用封装 |
 | `Tool` | 工具集合，管理所有可调用工具 |
+| `State` | 状态管理，支持检查点和持久化 |
 
 ## 项目结构
 
 ```
 rootdriver/
-├── agent.py          # Agent 智能体
-├── engine.py         # 引擎核心
-├── conversation.py   # 对话管理
-├── llm/              # LLM 适配器
-├── tool/             # 工具系统
-├── types/            # 类型定义
-└── utils/            # 工具函数
+├── 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

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rootdriver"
-version = "0.1.0"
+version = "0.2.0"
 description = "Rooted in Origin, Driving All Things"
 readme = "README.md"
 license = {text = "MIT"}

rootdriver-0.2.0/rootdriver/__init__.py

@@ -0,0 +1,58 @@
+__version__ = "0.2.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.2.0}/rootdriver/agent.py

@@ -6,7 +6,7 @@ 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,
+        # 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,

{rootdriver-0.1.0 → rootdriver-0.2.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.2.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.2.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.1.0 → rootdriver-0.2.0}/rootdriver.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rootdriver
-Version: 0.1.0
+Version: 0.2.0
 Summary: Rooted in Origin, Driving All Things
 Author-email: zimvir <zimvir@qq.com>
 License: MIT
@@ -13,16 +13,17 @@ Requires-Dist: pytest>=7.0.0; extra == "dev"
 
 # RootDriver
 
-根源出发， 驱动万物
+根源出发，驱动万物
 
-一个轻量级的 Python AI Agent 开发框架。
+一个轻量级的 Python AI Agent 开发框架，支持单智能体和多智能体应用。
 
 ## 特性
 
 - **简洁易用**：装饰器方式定义工具，快速构建 Agent
 - **模块化设计**：LLM 适配器、工具系统、会话管理解耦
 - **工具调用**：支持 function calling，自动执行工具并返回结果
-- **多适配器**：基于适配器模式，方便扩展其他 LLM Provider
+- **状态管理**：支持内存和数据库持久化检查点
+- **异常体系**：完整的异常类层次结构
 
 ## 安装
 
@@ -47,16 +48,15 @@ def get_weather(city: str) -> str:
 
 ```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,
+    agent_llm=AgentLLM(
+        adapter=OpenAIAdapter(
+            api_key="YOUR_API_KEY",
+            base_url="BASE_URL"
+        ),
+        model="gpt-4",
+    ),
     tools=[get_weather],
     system_prompt="你是一个有用的助手",
 )
@@ -70,7 +70,7 @@ print(response)
 
 ```python
 # 完整对话循环（包含工具调用）
-response = Agent.react("帮我查下上海天气")
+response = agent.react("帮我查下上海天气")
 print(response)
 ```
 
@@ -83,18 +83,27 @@ print(response)
 | `Conversation` | 会话管理，维护消息历史 |
 | `LLM` | LLM 调用封装 |
 | `Tool` | 工具集合，管理所有可调用工具 |
+| `State` | 状态管理，支持检查点和持久化 |
 
 ## 项目结构
 
 ```
 rootdriver/
-├── agent.py          # Agent 智能体
-├── engine.py         # 引擎核心
-├── conversation.py   # 对话管理
-├── llm/              # LLM 适配器
-├── tool/             # 工具系统
-├── types/            # 类型定义
-└── utils/            # 工具函数
+├── 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

{rootdriver-0.1.0 → rootdriver-0.2.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

{rootdriver-0.1.0 → rootdriver-0.2.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.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 @@
-