rootdriver 0.3.0__tar.gz → 0.4.0__tar.gz

{rootdriver-0.3.0/rootdriver.egg-info → rootdriver-0.4.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: rootdriver
-Version: 0.3.0
-Summary: Rooted in Origin, Driving All Things
+Version: 0.4.0
+Summary: Start from Root, Driving All Things
 Author-email: zimvir <zimvir@qq.com>
 License: MIT
 Requires-Python: >=3.10
@@ -15,7 +15,13 @@ Requires-Dist: pytest>=7.0.0; extra == "dev"
 
 根源出发，驱动万物
 
-一个轻量级的 Python AI Agent 开发框架，支持单智能体和多智能体应用。
+一个轻量级的 Python AI Agent 开发框架。
+
+**解决痛点：**
+
+- 想快速跑一个 Agent？一行代码，不需要编排、不需要懂设计模式
+- 市面框架太重、太复杂、学习成本高？RootDriver 核心代码几千行，不用记几百个 API
+- 需要扩展？按需添加，想加什么加什么，不被框架绑架
 
 ## 特性
 
@@ -24,7 +30,7 @@ Requires-Dist: pytest>=7.0.0; extra == "dev"
 - **工具调用**：支持 function calling，自动执行工具并返回结果
 - **状态管理**：支持内存和数据库持久化检查点
 - **异常体系**：完整的异常类层次结构
-- **异步支持**：全面异步支持，并发多 Agent / 工具调用
+- **异步支持**：全面异步支持，并发 Agent / 工具调用
 
 ## 安装
 
@@ -50,19 +56,23 @@ def get_weather(city: str) -> str:
 ```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",
+agent_llm = AgentLLM(
+    adapter=OpenAIAdapter(
+        api_key="YOUR_API_KEY",
+        base_url="BASE_URL"
     ),
+    model= "gpt-4",
+    temperature=0.7
+    )
+
+
+agent = Agent(
+    agent_llm=agent_llm,
     tools=[get_weather],
     system_prompt="你是一个有用的助手",
 )
 
-# 单次对话
+# 单次对话(无 tool)
 response = agent.talk("北京天气怎么样？")
 print(response)
 ```
@@ -82,7 +92,6 @@ import asyncio
 from rootdriver import Agent, AgentLLM, OpenAIAdapter
 
 async def main():
-    agent = Agent(agent_llm=AgentLLM(...))
 
     # 单次异步对话
     response = await agent.atalk("你好")
@@ -98,6 +107,39 @@ async def main():
 asyncio.run(main())
 ```
 
+## 记忆持久化
+
+Agent 支持对话历史自动持久化到 JSON 文件：
+
+```python
+agent = Agent(
+    agent_llm=agent_llm,
+    system_prompt="你是一个有用的助手",
+    db_path="conversations.json",     # 记忆数据库路径
+    auto_save=True,            # 开启自动保存（默认开启）
+)
+
+# 对话自动增量保存到 memory.json
+response = agent.react("我们之前聊了什么？")
+
+# 新建 Agent 时可从数据库恢复对话历史
+agent2 = Agent(agent_llm=agent_llm, id="same_user", db_path="memory.json")
+agent2.state.load_from_db("auto_saved")  # 恢复对话
+```
+
+### 手动检查点
+
+```python
+# 内存快照
+agent.state.checkpoint("backup_point")
+
+# 保存到数据库
+agent.state.save_from_checkpoints(name="my_backup", checkpoint_name="backup_point")
+
+# 从数据库加载
+agent.state.load_from_db("my_backup")
+```
+
 ## 核心组件
 
 | 组件 | 说明 |
@@ -108,6 +150,7 @@ asyncio.run(main())
 | `LLM` | LLM 调用封装 |
 | `Tool` | 工具集合，管理所有可调用工具 |
 | `State` | 状态管理，支持检查点和持久化 |
+| `JsonDB` | JSON 文件数据库封装 |
 
 ## 项目结构
 
@@ -116,7 +159,10 @@ rootdriver/
 ├── agent.py           # Agent 智能体
 ├── engine.py          # 引擎核心
 ├── conversation.py    # 对话管理
-├── state.py           # 状态管理
+├── state/             # 状态管理包
+│   └── state.py       # State 实现
+├── db/                # 数据库封装包
+│   └── json_db.py     # JsonDB 实现
 ├── exception.py       # 异常定义
 ├── llm/
 │   ├── llm.py         # LLM 封装

rootdriver-0.3.0/PKG-INFO → rootdriver-0.4.0/README.md

@@ -1,135 +1,168 @@
-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
+
+根源出发，驱动万物
+
+一个轻量级的 Python AI Agent 开发框架。
+
+**解决痛点：**
+
+- 想快速跑一个 Agent？一行代码，不需要编排、不需要懂设计模式
+- 市面框架太重、太复杂、学习成本高？RootDriver 核心代码几千行，不用记几百个 API
+- 需要扩展？按需添加，想加什么加什么，不被框架绑架
+
+## 特性
+
+- **简洁易用**：装饰器方式定义工具，快速构建 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_llm = AgentLLM(
+    adapter=OpenAIAdapter(
+        api_key="YOUR_API_KEY",
+        base_url="BASE_URL"
+    ),
+    model= "gpt-4",
+    temperature=0.7
+    )
+
+
+agent = Agent(
+    agent_llm=agent_llm,
+    tools=[get_weather],
+    system_prompt="你是一个有用的助手",
+)
+
+# 单次对话(无 tool)
+response = agent.talk("北京天气怎么样？")
+print(response)
+```
+
+### 使用工具
+
+```python
+# 完整对话循环（包含工具调用）
+response = agent.react("帮我查下上海天气")
+print(response)
+```
+
+### 异步用法
+
+```python
+import asyncio
+from rootdriver import Agent, AgentLLM, OpenAIAdapter
+
+async def main():
+
+    # 单次异步对话
+    response = await agent.atalk("你好")
+    print(response)
+
+    # 并发多个 Agent
+    results = await asyncio.gather(
+        agent.areact("问题1"),
+        agent.areact("问题2"),
+        agent.areact("问题3"),
+    )
+
+asyncio.run(main())
+```
+
+## 记忆持久化
+
+Agent 支持对话历史自动持久化到 JSON 文件：
+
+```python
+agent = Agent(
+    agent_llm=agent_llm,
+    system_prompt="你是一个有用的助手",
+    db_path="conversations.json",     # 记忆数据库路径
+    auto_save=True,            # 开启自动保存（默认开启）
+)
+
+# 对话自动增量保存到 memory.json
+response = agent.react("我们之前聊了什么？")
+
+# 新建 Agent 时可从数据库恢复对话历史
+agent2 = Agent(agent_llm=agent_llm, id="same_user", db_path="memory.json")
+agent2.state.load_from_db("auto_saved")  # 恢复对话
+```
+
+### 手动检查点
+
+```python
+# 内存快照
+agent.state.checkpoint("backup_point")
+
+# 保存到数据库
+agent.state.save_from_checkpoints(name="my_backup", checkpoint_name="backup_point")
+
+# 从数据库加载
+agent.state.load_from_db("my_backup")
+```
+
+## 核心组件
+
+| 组件 | 说明 |
+|------|------|
+| `Agent` | 智能体入口，整合 LLM、工具、会话 |
+| `Engine` | 核心引擎，处理对话循环和工具调用 |
+| `Conversation` | 会话管理，维护消息历史 |
+| `LLM` | LLM 调用封装 |
+| `Tool` | 工具集合，管理所有可调用工具 |
+| `State` | 状态管理，支持检查点和持久化 |
+| `JsonDB` | JSON 文件数据库封装 |
+
+## 项目结构
+
+```
+rootdriver/
+├── agent.py           # Agent 智能体
+├── engine.py          # 引擎核心
+├── conversation.py    # 对话管理
+├── state/             # 状态管理包
+│   └── state.py       # State 实现
+├── db/                # 数据库封装包
+│   └── json_db.py     # JsonDB 实现
+├── 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 → rootdriver-0.4.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rootdriver"
-version = "0.3.0"
-description = "Rooted in Origin, Driving All Things"
+version = "0.4.0"
+description = "Start from Root, Driving All Things"
 readme = "README.md"
 license = {text = "MIT"}
 authors = [

{rootdriver-0.3.0 → rootdriver-0.4.0}/rootdriver/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 __author__ = "zimvir"
 __email__ = "zimvir@qq.com"
 
@@ -6,6 +6,7 @@ from .agent import Agent
 from .engine import Engine
 from .conversation import Conversation
 from .state import State
+from . import db
 from .llm import LLM
 from .llm.base_adapter import BaseAdapter
 from .llm.adapter import OpenAIAdapter
@@ -26,6 +27,8 @@ from .exception import (
     CheckpointNotFoundError,
     StateSaveError,
     StateLoadError,
+    StateDBNotFoundError,
+    DBNotFoundError,
 )
 
 __all__ = [
@@ -33,6 +36,7 @@ __all__ = [
     "Engine",
     "Conversation",
     "State",
+    "db",
     "LLM",
     "BaseAdapter",
     "OpenAIAdapter",
@@ -55,4 +59,6 @@ __all__ = [
     "CheckpointNotFoundError",
     "StateSaveError",
     "StateLoadError",
+    "StateDBNotFoundError",
+    "DBNotFoundError",
 ]

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

@@ -7,7 +7,8 @@ from .conversation import Conversation
 from .tool import Tool, BaseTool
 from .types.agent import AgentLLM
 from .state import State
-from .utils import build_system_message, build_message, build_tool_message, build_user_message, build_assistant_message
+from .utils import build_user_message, ensure_file_exist
+from .constants import DEFAULT_AGENT_DB_PATH
 
 class Agent:
 
@@ -19,23 +20,31 @@ class Agent:
         system_prompt: str | None = None,
 
         db_path: str| None = None,
+        auto_save: bool = True,
         # llm_retry: int = 3,
         # timeout: float | None = None,
     ):
+        # 检查信息
+        ensure_file_exist(db_path,"{}")
+
+        # 初始化模块
         self.id = id if id else uuid4().hex
-        self.db_path = db_path
+        self.db_path = DEFAULT_AGENT_DB_PATH
+        self.auto_save = auto_save
 
         self.conversation = Conversation(system_prompt)
         self.tool = Tool(tools if tools else [])
-        self.state = State(self, self.db_path)
+        self.state = State(self, self.db_path, self.auto_save)
 
         self.engine = Engine(
             model=agent_llm.model,
             llm=LLM(agent_llm.adapter),
             conversation=self.conversation,
             tool=self.tool,
+            _agent=self,
         )
-
+        # 属性初始化
+        self.state.update_auto_save_data_saved_length()
 
     def react(self, input_prompt:str) -> "str":
         """一次 react 循环"""

rootdriver-0.4.0/rootdriver/constants.py

@@ -0,0 +1,4 @@
+ROLE_ENUM = ("system", "user", "assistant", "tool")
+
+DEFAULT_AGENT_STATE_AUTO_SAVE_NAME = "auto_saved"
+DEFAULT_AGENT_DB_PATH = "conversations.json"

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

@@ -54,8 +54,12 @@ class Conversation:
 
     def get_messages_in_list(self) -> list[dict]:
         '''返回 字典加列表组成的message（可转成json用于网络、跨语言传输） 组成的列表'''
-        return [m.model_dump(exclude_none=True) for m in self.messages]
-
+        return [m.model_dump(exclude_none=False) for m in self.messages]
+    def get_message_by_index(self, index: int=-1) -> Message:
+        return self.messages[index]
+    def get_message_in_list_by_index(self, index:int=-1) -> list[dict]:
+        """据索引返回当前消息列表的"""
+        return self.messages[index].model_dump(exclude_none=False)
     @classmethod
     def from_dict_list(cls, messages: list[dict]) -> "Conversation":
         conv = cls()
@@ -73,3 +77,10 @@ class Conversation:
         self.messages = []
         return self
 
+    def copy(self) -> "Conversation":
+        """返回当前 conversation 的浅拷贝"""
+        new_conv = Conversation()
+        new_conv.messages = list(self.messages)
+        new_conv.system_prompt = self.system_prompt
+        return new_conv
+