KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #ai-agent #developer-tools #claude-code #codex #deepseek-harness #ai-agents #cli #react #mcp

pydantic-ai-todo

★ 75 Open GitHub ↗

Task Planning and Tracking toolset for Pydantic AI agents, enabling hierarchical task management with subtasks, PostgreSQL storage for multi-tenancy, and an event system for webhooks and callbacks.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">Todo Toolset for Pydantic AI</h1>

Task Planning and Tracking for AI Agents

Capabilities API — plug-and-play with one line
 &nbsp;&bull;&nbsp;
 Subtasks & Dependencies — hierarchical task management
 &nbsp;&bull;&nbsp;
 PostgreSQL Storage — persistent multi-tenant tasks
 &nbsp;&bull;&nbsp;
 Event System — webhooks and callbacks

---

> ### ⬆️ Upstreamed to `pydantic-ai-harness`
>
> Working together with the Pydantic team, we folded this library into the official
> **[pydantic-ai-harness](https://github.com/pydantic/pydantic-ai-harness)** — it now lives in
> [`pydantic_ai_harness/planning`](https://github.com/pydantic/pydantic-ai-harness/tree/main/pydantic_ai_harness/planning)
> ([PR #404](https://github.com/pydantic/pydantic-ai-harness/pull/404), merged), which supersedes this package.
>
> **For new projects, use the harness** — it is maintained by Pydantic alongside Pydantic AI itself. This
> repository stays on PyPI and keeps working for everyone already depending on it.
>
> ```python
> from pydantic_ai import Agent
> from pydantic_ai_harness.planning import Planning
>
> agent = Agent("openai:gpt-5.4", capabilities=[Planning(enable_subtasks=True)])
> ```
>
> **Tools were renamed**
>
> | Here | In the harness |
> |---|---|
> | `write_todos` | `write_plan` |
> | `read_todos` | `read_plan` |
> | `add_todo` | `add_task` |
> | `update_todo_status` / `update_todo_statuses` | `update_task_status` / `update_task_statuses` |
> | `remove_todo` | `remove_task` |
> | `add_subtask`, `set_dependency`, `get_available_tasks` | unchanged |
>
> **API mapping**
>
> | Here | In `pydantic_ai_harness.planning` |
> |---|---|
> | `TodoCapability` | `Planning` |
> | `TodoStorage`, `AsyncMemoryStorage` | `InMemoryPlanStore` |
> | `AsyncPostgresStorage` / `create_storage("postgres", connection_string=…)` | `PostgresPlanStore` — takes a **caller-owned** asyncpg-compatible pool, so the harness pulls in no database driver |
> | `create_todo_toolset()` | `PlanningToolset` |
> | `get_todo_system_prompt()` | not needed — `Planning` surfaces the plan as an ephemeral tail reminder behind a `CachePoint`, so the cached prefix stays byte-identical across turns |
> | `Todo`, `TodoItem` | `PlanItem` |
> | `TodoEvent`, `TodoEventType`, `TodoEventEmitter` | `PlanEvent`, `PlanEventType`, `PlanEventEmitter` |
>
> The harness also adds `SqlitePlanStore` and `RedisPlanStore`, and a `blocked` task status, none of which
> exist here.

**Todo Toolset for Pydantic AI** adds task planning capabilities to any [Pydantic AI](https://ai.pydantic.dev/) agent. Your agent can create, track, and complete tasks with full support for subtasks, dependencies, and persistent storage.

> **Full framework?** Check out [Pydantic Deep Agents](https://github.com/vstorm-co/pydantic-deepagents) — complete agent framework with planning, filesystem, subagents, and skills.

## Quick Start

The recommended way to add todo support is via the **Capabilities API** — one import, one line:

```python
from pydantic_ai import Agent
from pydantic_ai_todo import TodoCapability

agent = Agent("openai:gpt-4.1", capabilities=[TodoCapability()])
result = await agent.run("Create a todo list for building a REST API")
```

`TodoCapability` automatically:
- Registers all todo tools (`add_todo`, `read_todos`, `write_todos`, `update_todo_status`, `remove_todo`)
- Injects a system prompt section describing the todo workflow (static by default,
  so todo updates never invalidate the provider's prompt cache; pass
  `include_current_todos=True` to embed the live task list instead)
- Creates in-memory storage (or use your own)

### With Storage Access

```python
from pydantic_ai_todo import TodoCapability, TodoStorage

storage = TodoStorage()
agent = Agent("openai:gpt-4.1", capabilities=[TodoCapability(storage=storage)])

result = await agent.run("Plan a blog application")

# Access todos directly
for todo in storage.todos:
    print(f"[{todo.status}] {todo.content}")
```

### With Subtasks and Dependencies

```python
agent = Agent(
    "openai:gpt-4.1",
    capabilities=[TodoCapability(enable_subtasks=True)],
)
```

Enables `add_subtask`, `set_dependency`, and `get_available_tasks` tools with automatic cycle detection.

### YAML Agent Definition

```yaml
model: openai:gpt-4.1
instructions: "You are a project planner."
capabilities:
  - TodoCapability:
      enable_subtasks: true
```

```python
agent = Agent.from_file("agent.yaml")
```

## Installation

```bash
pip install pydantic-ai-todo
```

Or with uv:

```bash
uv add pydantic-ai-todo
```

## Alternative: Toolset API

If you prefer the lower-level toolset approach (without capabilities):

```python
from pydantic_ai import Agent
from pydantic_ai_todo import create_todo_toolset, get_todo_system_prompt, TodoStorage

storage = TodoStorage()
toolset = create_todo_toolset(storage=storage)

agent = Agent(
    "openai:gpt-4.1",
    toolsets=[toolset],
    system_prompt=get_todo_system_prompt(storage),
)
```

> **Note:** With the toolset API, you need to wire `get_todo_system_prompt()` manually. `TodoCapability` handles this automatically.

## Available Tools

| Tool | Description |
|------|-------------|
| `read_todos` | List all tasks (supports hierarchical view) |
| `write_todos` | Bulk write/update tasks |
| `add_todo` | Add a single task |
| `update_todo_status` | Update task status by ID |
| `remove_todo` | Delete task by ID |
| `add_subtask`* | Create child task |
| `set_dependency`* | Link tasks with dependency |
| `get_available_tasks`* | List tasks ready to work on |

*Available when `enable_subtasks=True`

## Storage Backends

### In-Memory (Default)

```python
from pydantic_ai_todo import TodoCapability, TodoStorage

storage = TodoStorage()
agent = Agent("openai:gpt-4.1", capabilities=[TodoCapability(storage=storage)])
```

### Async Memory

```python
from pydantic_ai_todo import TodoCapability, AsyncMemoryStorage

storage = AsyncMemoryStorage()
agent = Agent("openai:gpt-4.1", capabilities=[TodoCapability(async_storage=storage)])
```

### PostgreSQL

> Requires the `postgres` extra: `pip install 'pydantic-ai-todo[postgres]'`

```python
from pydantic_ai_todo import TodoCapability, create_storage

storage = create_storage(
    "postgres",
    connection_string="postgresql://user:pass@localhost/db",
    session_id="user-123",  # Multi-tenancy
)
await storage.initialize()

agent = Agent("openai:gpt-4.1", capabilities=[TodoCapability(async_storage=storage)])
```

## Event System

React to task changes:

```python
from pydantic_ai_todo import TodoCapability, TodoEventEmitter, AsyncMemoryStorage

emitter = TodoEventEmitter()

@emitter.on_completed
async def notify_completed(event):
    print(f"Task done: {event.todo.content}")

@emitter.on_created
async def notify_created(event):
    print(f"New task: {event.todo.content}")

storage = AsyncMemoryStorage(event_emitter=emitter)
agent = Agent("openai:gpt-4.1", capabilities=[TodoCapability(async_storage=storage)])
```

## API Reference

### Capability

| Class | Description |
|-------|-------------|
| `TodoCapability` | Pydantic AI capability — recommended way to add todo support |

### Factory Functions

| Function | Description |
|----------|-------------|
| `create_todo_toolset()` | Create standalone toolset (lower-level API) |
| `create_storage(backend, **options)` | Factory for storage backends |
| `get_todo_system_prompt()` | Generate system prompt with current todos |

### Models

| Model | Description |
|-------|-------------|
| `Todo` | Task with id, content, status, parent_id, depends_on |
| `TodoItem` | Input model for write_todos |
| `TodoEvent` | Event data with type, todo, timestamp |
| `TodoEventType` | CREATED, UPDATED, STATUS_CHANGED, DELETED, COMPLETED |

### Storage Classes

| Class | Description |
|-------|-------------|
| `TodoStorage` | Sync in-memory storage |
| `AsyncMemoryStorage` | Async in-memory with CRUD |
| `AsyncPostgresStorage` | PostgreSQL with multi-tenancy |
| `TodoEventEmitter` | Event emitter for callbacks |

## Related Projects

| Package | Description |
|---------|-------------|
| [Pydantic Deep Agents](https://github.com/vstorm-co/pydantic-deepagents) | Full agent framework (uses this library) |
| [pydantic-ai-backend](https://github.com/vstorm-co/pydantic-ai-backend) | File storage and Docker sandbox |
| [subagents-pydantic-ai](https://github.com/vstorm-co/subagents-pydantic-ai) | Multi-agent orchestration |
| [summarization-pydantic-ai](https://github.com/vstorm-co/summarization-pydantic-ai) | Context management |
| [pydantic-ai](https://github.com/pydantic/pydantic-ai) | The foundation — agent framework by Pydantic |

## Contributing

```bash
git clone https://github.com/vstorm-co/pydantic-ai-todo.git
cd pydantic-ai-todo
make install
make test  # 100% coverage required
```

## License

MIT — see [LICENSE](LICENSE)

---

### Need help implementing this in your company?

We're <a href="https://vstorm.co">Vstorm</a> — an Applied Agentic AI Engineering Consultancy with 30+ production AI agent implementations.

Made with ❤️ by <a href="https://vstorm.co">Vstorm</a>

</div>

pydantic-ai-todo

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README