Merge pull request #11 from vstorm-co/extract-todo

refactor: extract todo toolset to pydantic-ai-todo

Author: DEENUU1

README.md

@@ -2,6 +2,8 @@
 
 > **Looking for a full-stack template?** Check out [fastapi-fullstack](https://github.com/vstorm-co/full-stack-fastapi-nextjs-llm-template) - a production-ready project generator for AI/LLM applications with FastAPI, Next.js, and pydantic-deep integration.
 
+> **Need just the todo toolset?** Check out [pydantic-ai-todo](https://github.com/vstorm-co/pydantic-ai-todo) - standalone task planning toolset that works with any pydantic-ai agent.
+
 [![PyPI version](https://img.shields.io/pypi/v/pydantic-deep.svg)](https://pypi.org/project/pydantic-deep/)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

docs/api/toolsets.md

@@ -2,30 +2,48 @@
 
 ## TodoToolset
 
-Task planning and tracking tools.
+Task planning and tracking tools. Provided by [pydantic-ai-todo](https://github.com/vstorm-co/pydantic-ai-todo).
 
 ### Tools
 
 | Tool | Description |
 |------|-------------|
+| `read_todos` | Read the current todo list state |
 | `write_todos` | Update the todo list |
 
 ### Factory
 
 ```python
+from pydantic_ai_todo import create_todo_toolset
+
 def create_todo_toolset(
+    storage: TodoStorageProtocol | None = None,
     *,
-    id: str = "todo",
-) -> TodoToolset
+    id: str | None = None,
+) -> FunctionToolset[Any]
+```
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `storage` | `TodoStorageProtocol \| None` | `None` | Storage backend (defaults to in-memory) |
+| `id` | `str \| None` | `None` | Optional unique ID for the toolset |
+
+### Tool: read_todos
+
+```python
+async def read_todos() -> str
 ```
 
+Read the current todo list state.
+
+**Returns:** Formatted list of todos with status icons and summary.
+
 ### Tool: write_todos
 
 ```python
-async def write_todos(
-    ctx: RunContext[DeepAgentDeps],
-    todos: list[dict],
-) -> str
+async def write_todos(todos: list[TodoItem]) -> str
 ```
 
 Update the todo list with new items.
@@ -34,7 +52,7 @@ Update the todo list with new items.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `todos` | `list[dict]` | List of todo items |
+| `todos` | `list[TodoItem]` | List of todo items |
 
 Each todo item:
 ```python
@@ -45,16 +63,49 @@ Each todo item:
 }
 ```
 
-**Returns:** Confirmation message.
+**Returns:** Confirmation message with status counts.
+
+### Types
+
+```python
+from pydantic_ai_todo import Todo, TodoItem, TodoStorage, TodoStorageProtocol
+
+class Todo(BaseModel):
+    content: str
+    status: Literal["pending", "in_progress", "completed"]
+    active_form: str
+
+class TodoStorage:
+    """Default in-memory storage."""
+    todos: list[Todo]
+```
 
 ### System Prompt
 
 ```python
-def get_todo_system_prompt(deps: DeepAgentDeps) -> str
+from pydantic_ai_todo import get_todo_system_prompt
+
+def get_todo_system_prompt(storage: TodoStorageProtocol | None = None) -> str
 ```
 
 Generates dynamic system prompt showing current todos.
 
+### Standalone Usage
+
+```python
+from pydantic_ai import Agent
+from pydantic_ai_todo import create_todo_toolset, TodoStorage
+
+# Simple usage
+agent = Agent("openai:gpt-4.1", toolsets=[create_todo_toolset()])
+
+# With storage access
+storage = TodoStorage()
+agent = Agent("openai:gpt-4.1", toolsets=[create_todo_toolset(storage)])
+result = await agent.run("Create 3 tasks")
+print(storage.todos)  # Access todos directly
+```
+
 ---
 
 ## FilesystemToolset

docs/concepts/toolsets.md

@@ -6,10 +6,11 @@ Toolsets are collections of tools that extend agent capabilities. pydantic-deep
 
 ### TodoToolset
 
-Task planning and tracking.
+Task planning and tracking. Powered by [pydantic-ai-todo](https://github.com/vstorm-co/pydantic-ai-todo).
 
 | Tool | Description |
 |------|-------------|
+| `read_todos` | Read the current todo list state |
 | `write_todos` | Update the todo list with tasks and statuses |
 
 ```python
@@ -26,6 +27,17 @@ write_todos(todos=[
 - `in_progress` - Currently working
 - `completed` - Done
 
+!!! tip "Standalone Usage"
+    The todo toolset can also be used independently with any pydantic-ai agent:
+
+    ```python
+    from pydantic_ai import Agent
+    from pydantic_ai_todo import create_todo_toolset, TodoStorage
+
+    storage = TodoStorage()
+    agent = Agent("openai:gpt-4.1", toolsets=[create_todo_toolset(storage)])
+    ```
+
 ### FilesystemToolset
 
 File operations using the configured backend.

pydantic_deep/agent.py

@@ -10,6 +10,7 @@
 from pydantic_ai.models import Model
 from pydantic_ai.output import OutputSpec
 from pydantic_ai.tools import DeferredToolRequests, Tool
+from pydantic_ai_todo import create_todo_toolset, get_todo_system_prompt
 
 from pydantic_deep.backends.protocol import BackendProtocol, SandboxProtocol
 from pydantic_deep.backends.state import StateBackend
@@ -20,7 +21,6 @@
 )
 from pydantic_deep.toolsets.skills import create_skills_toolset, get_skills_system_prompt
 from pydantic_deep.toolsets.subagents import create_subagent_toolset, get_subagent_system_prompt
-from pydantic_deep.toolsets.todo import create_todo_toolset, get_todo_system_prompt
 from pydantic_deep.types import Skill, SkillDirectory, SubAgentConfig
 
 if TYPE_CHECKING:

pydantic_deep/toolsets/__init__.py

@@ -1,9 +1,11 @@
 """Toolsets for pydantic-deep agents."""
 
+# Re-export from pydantic-ai-todo
+from pydantic_ai_todo import create_todo_toolset as TodoToolset
+
 from pydantic_deep.toolsets.filesystem import FilesystemToolset
 from pydantic_deep.toolsets.skills import SkillsToolset
 from pydantic_deep.toolsets.subagents import SubAgentToolset
-from pydantic_deep.toolsets.todo import TodoToolset
 
 __all__ = [
     "TodoToolset",

pydantic_deep/toolsets/subagents.py

@@ -122,8 +122,9 @@ async def task(  # pragma: no cover
             subagent = ctx.deps.subagents[subagent_type]
         else:
             # Create the subagent on-the-fly
+            from pydantic_ai_todo import create_todo_toolset
+
             from pydantic_deep.toolsets.filesystem import create_filesystem_toolset
-            from pydantic_deep.toolsets.todo import create_todo_toolset
 
             model = config.get("model", default_model)
             tools = config.get("tools", [])