Metadata-Version: 2.4
Name: pydantic-deep
Version: 0.3.0
Summary: Deep Agent framework built on Pydantic-ai with planning, filesystem, and subagent capabilities
Project-URL: Homepage, https://github.com/vstorm-co/pydantic-deepagents
Project-URL: Documentation, https://github.com/vstorm-co/pydantic-deepagents
Project-URL: Repository, https://github.com/vstorm-co/pydantic-deepagents
Project-URL: Issues, https://github.com/vstorm-co/pydantic-deepagents/issues
Author: Pydantic Deep Contributors
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: chardet>=5.0.0
Requires-Dist: pydantic-ai-backend[console]>=0.2.0
Requires-Dist: pydantic-ai-shields>=0.3.0
Requires-Dist: pydantic-ai-slim>=1.71.0
Requires-Dist: pydantic-ai-todo>=0.2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: subagents-pydantic-ai>=0.1.0
Requires-Dist: summarization-pydantic-ai>=0.1.0
Provides-Extra: all
Requires-Dist: fastapi>=0.125.0; extra == 'all'
Requires-Dist: logfire>=4.0; extra == 'all'
Requires-Dist: prompt-toolkit>=3.0.0; extra == 'all'
Requires-Dist: pydantic-ai-backend[docker]>=0.2.0; extra == 'all'
Requires-Dist: python-dotenv>=1.0.0; extra == 'all'
Requires-Dist: python-multipart>=0.0.21; extra == 'all'
Requires-Dist: pyyaml>=6.0; extra == 'all'
Requires-Dist: rich>=13.0.0; extra == 'all'
Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'all'
Requires-Dist: typer>=0.12.0; extra == 'all'
Requires-Dist: uvicorn>=0.38.0; extra == 'all'
Provides-Extra: cli
Requires-Dist: prompt-toolkit>=3.0.0; extra == 'cli'
Requires-Dist: python-dotenv>=1.0.0; extra == 'cli'
Requires-Dist: rich>=13.0.0; extra == 'cli'
Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'cli'
Requires-Dist: typer>=0.12.0; extra == 'cli'
Provides-Extra: logfire
Requires-Dist: logfire>=4.0; extra == 'logfire'
Provides-Extra: sandbox
Requires-Dist: pydantic-ai-backend[docker]>=0.2.0; extra == 'sandbox'
Provides-Extra: web
Requires-Dist: fastapi>=0.125.0; extra == 'web'
Requires-Dist: python-multipart>=0.0.21; extra == 'web'
Requires-Dist: uvicorn>=0.38.0; extra == 'web'
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == 'yaml'
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/baner.png" alt="pydantic-deep">
</p>

<h1 align="center">Pydantic Deep Agents</h1>

<p align="center">
  <b>From framework to terminal -- autonomous AI agents that plan, code, and ship</b>
</p>

<p align="center">
  <a href="https://vstorm-co.github.io/pydantic-deepagents/">Docs</a> &middot;
  <a href="https://pypi.org/project/pydantic-deep/">PyPI</a> &middot;
  <a href="#cli--terminal-ai-assistant">CLI</a> &middot;
  <a href="#deepresearch--reference-app">DeepResearch</a> &middot;
  <a href="https://vstorm-co.github.io/pydantic-deepagents/examples/">Examples</a>
</p>

<p align="center">
  <a href="https://pypi.org/project/pydantic-deep/"><img src="https://img.shields.io/pypi/v/pydantic-deep.svg" alt="PyPI version"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.10+"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
  <a href="https://coveralls.io/github/vstorm-co/pydantic-deepagents?branch=main"><img src="https://coveralls.io/repos/github/vstorm-co/pydantic-deepagents/badge.svg?branch=main" alt="Coverage Status"></a>
  <a href="https://github.com/vstorm-co/pydantic-deepagents/actions/workflows/ci.yml"><img src="https://github.com/vstorm-co/pydantic-deepagents/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://github.com/pydantic/pydantic-ai"><img src="https://img.shields.io/badge/Powered%20by-Pydantic%20AI-E92063?logo=pydantic&logoColor=white" alt="Pydantic AI"></a>
</p>

<p align="center">
  <b>Unlimited Context</b>
  &nbsp;&bull;&nbsp;
  <b>Subagent Delegation</b>
  &nbsp;&bull;&nbsp;
  <b>Persistent Memory</b>
  &nbsp;&bull;&nbsp;
  <b>Lifecycle Hooks</b>
</p>

---

### Same Architecture as the Best

pydantic-deep implements the **deep agent pattern** -- the same architecture powering:

| | Product | What They Built |
|:-:|---------|-----------------|
| | [**Claude Code**](https://claude.ai/code) | Anthropic's AI coding assistant |
| | [**Manus AI**](https://manus.ai) | Autonomous task execution |
| | [**Devin**](https://devin.ai) | AI software engineer |

**Now you can build the same thing** -- or just use the CLI.

> **Inspired by:** [LangChain's Deep Agents](https://github.com/langchain-ai/deepagents) research on autonomous agent architectures.

---

**pydantic-deep** is three things:

1. **A Python framework** for building Claude Code-style agents with planning, filesystem access, subagents, memory, and unlimited context
2. **A CLI** that gives you a terminal AI assistant out of the box
3. **DeepResearch** -- a full-featured research agent with web UI, web search, diagrams, and sandboxed code execution

---

## CLI -- Terminal AI Assistant

<p align="center">
  <img src="assets/cli_demo.gif" alt="pydantic-deep CLI demo" width="700">
</p>

```bash
pip install pydantic-deep[cli]
pydantic-deep chat
```

That's it. You get an interactive AI agent in your terminal with:

- File read/write/edit, shell execution, glob, grep
- Task planning and subagent delegation
- Persistent memory across sessions
- Context compression for unlimited conversations
- Git-aware project context
- Built-in commands: `/commit`, `/pr`, `/review`, `/test`, `/fix`, `/explain`
- Customizable skills, hooks, and output styles

```bash
# Interactive mode
pydantic-deep chat

# Run a single task
pydantic-deep run "Fix the failing tests in src/"

# Docker sandbox for isolated execution
pydantic-deep run "Build a web scraper" --sandbox

# Pick a model
pydantic-deep chat --model anthropic:claude-sonnet-4-20250514

# Manage config
pydantic-deep config set model openai:gpt-4.1
```

> See [CLI docs](docs/cli/index.md) for the full reference.

---

## Framework -- Build Your Own Agent

```bash
pip install pydantic-deep
```

**Requires pydantic-ai >= 1.71.0.**

```python
from pydantic_ai_backends import StateBackend
from pydantic_deep import create_deep_agent, create_default_deps

agent = create_deep_agent()
deps = create_default_deps(StateBackend())

result = await agent.run("Create a todo list for building a REST API", deps=deps)
```

One function call gives you an agent with planning, filesystem tools, subagents, skills, context management, and cost tracking. Everything is toggleable:

```python
agent = create_deep_agent(
    model="openai:gpt-4.1",
    include_todo=True,          # Task planning
    include_filesystem=True,    # File read/write/edit/execute
    include_subagents=True,     # Delegate to subagents
    include_skills=True,        # Domain-specific skills from SKILL.md files
    include_memory=True,        # Persistent MEMORY.md across sessions
    include_plan=True,          # Structured planning before execution
    include_teams=True,         # Multi-agent teams with shared TODOs
    include_web=True,           # Built-in WebSearch() and WebFetch() capabilities
    context_manager=True,       # Auto-summarization for unlimited context
    cost_tracking=True,         # Token/USD budget enforcement
    include_checkpoints=True,   # Save, rewind, and fork conversations
)
```

### Structured Output

```python
from pydantic import BaseModel

class CodeReview(BaseModel):
    summary: str
    issues: list[str]
    score: int

agent = create_deep_agent(output_type=CodeReview)
result = await agent.run("Review the auth module", deps=deps)
print(result.output.score)  # Type-safe!
```

### Context Management

```python
from pydantic_deep import create_summarization_processor

processor = create_summarization_processor(
    trigger=("tokens", 100000),
    keep=("messages", 20),
)
agent = create_deep_agent(history_processors=[processor])
```

### Hooks (Claude Code-Style)

```python
from pydantic_deep import Hook, HookEvent

agent = create_deep_agent(
    hooks=[
        Hook(
            event=HookEvent.PRE_TOOL_USE,
            command="echo 'Tool called: $TOOL_NAME' >> /tmp/audit.log",
        ),
    ],
)
```

### Cost Tracking

```python
agent = create_deep_agent(
    cost_tracking=True,
    cost_budget_usd=5.0,
    on_cost_update=lambda info: print(f"Cost: ${info.total_usd:.4f}"),
)
```

### Custom Subagents

```python
agent = create_deep_agent(
    subagents=[
        {
            "name": "code-reviewer",
            "description": "Reviews code for quality issues",
            "instructions": "You are a senior code reviewer...",
            "preferred_mode": "sync",
        },
    ],
)
```

> See the full [API reference](https://vstorm-co.github.io/pydantic-deepagents/api/toolsets/) for all options.

---

## DeepResearch -- Reference App

A full-featured research agent with web UI, built entirely on pydantic-deep.

<table>
<tr>
<td width="50%">
<a href="apps/deepresearch/"><img src="assets/planner_asks_question.png" alt="Planner subagent asks clarifying questions"></a>
<p align="center"><b>Plan Mode</b> -- planner asks clarifying questions</p>
</td>
<td width="50%">
<a href="apps/deepresearch/"><img src="assets/spawn_subagents_deepresearch.png" alt="Parallel subagent research"></a>
<p align="center"><b>Parallel Subagents</b> -- 5 agents researching simultaneously</p>
</td>
</tr>
<tr>
<td width="50%">
<a href="apps/deepresearch/"><img src="assets/excalidraw_in_deepresearch.png" alt="Excalidraw canvas"></a>
<p align="center"><b>Excalidraw Canvas</b> -- live diagrams synced with agent</p>
</td>
<td width="50%">
<a href="apps/deepresearch/"><img src="assets/display_files_deepresearch.png" alt="File browser"></a>
<p align="center"><b>File Browser</b> -- workspace files with inline preview</p>
</td>
</tr>
</table>

Web search (Tavily, Brave, Jina), sandboxed code execution, Excalidraw diagrams, subagents, plan mode, report export, and more.

```bash
cd apps/deepresearch
uv sync
cp .env.example .env  # Add your API keys
uv run deepresearch    # Open http://localhost:8080
```

> See [apps/deepresearch/README.md](apps/deepresearch/README.md) for full setup.

---

## Architecture

pydantic-deep v0.3.0 uses pydantic-ai's native **Capabilities API** (`Agent(capabilities=[...])`) for all cross-cutting concerns. This replaces the previous middleware wrapping approach and provides a cleaner, more composable architecture.

### Capabilities

All lifecycle features are implemented as capabilities that extend `AbstractCapability` from pydantic-ai:

| Capability | Package | What It Does |
|-----------|---------|--------------|
| **CostTracking** | [pydantic-ai-shields](https://github.com/vstorm-co/pydantic-ai-shields) | Token/USD budget enforcement and real-time cost callbacks |
| **ContextManagerCapability** | [summarization-pydantic-ai](https://github.com/vstorm-co/summarization-pydantic-ai) | Auto-compression when approaching token budget |
| **HooksCapability** | pydantic-deep | Claude Code-style lifecycle hooks on tool events |
| **CheckpointMiddleware** | pydantic-deep | Save, rewind, and fork conversation state |
| **WebSearch / WebFetch** | pydantic-ai (built-in) | Web search and URL fetching |

pydantic-deep also provides 5 **internal capabilities** that are automatically wired up when their corresponding `include_*` flags are set:

| Internal Capability | Activated By | What It Does |
|-----------|---------|--------------|
| **SkillsCapability** | `include_skills=True` | Domain-specific skills from SKILL.md files |
| **ContextFilesCapability** | `context_files` / `context_discovery` | Auto-discover and inject DEEP.md, AGENTS.md, CLAUDE.md |
| **MemoryCapability** | `include_memory=True` | Persistent MEMORY.md across sessions |
| **TeamCapability** | `include_teams=True` | Multi-agent teams with shared TODOs and message bus |
| **PlanCapability** | `include_plan=True` | Structured planning before execution |

### Component Packages

Every component is modular and works standalone:

| Component | Package | What It Does |
|-----------|---------|--------------|
| **Backends** | [pydantic-ai-backend](https://github.com/vstorm-co/pydantic-ai-backend) | File storage, Docker/Daytona sandbox |
| **Planning** | [pydantic-ai-todo](https://github.com/vstorm-co/pydantic-ai-todo) | Task tracking with dependencies |
| **Subagents** | [subagents-pydantic-ai](https://github.com/vstorm-co/subagents-pydantic-ai) | Sync/async delegation, cancellation |
| **Summarization** | [summarization-pydantic-ai](https://github.com/vstorm-co/summarization-pydantic-ai) | LLM summaries or sliding window |
| **Shields** | [pydantic-ai-shields](https://github.com/vstorm-co/pydantic-ai-shields) | Cost tracking, input/output/tool blocking |

```
                              pydantic-deep
+---------------------------------------------------------------------+
|                                                                     |
|   +----------+ +----------+ +----------+ +----------+ +---------+   |
|   | Planning | |Filesystem| | Subagents| |  Skills  | |  Teams  |   |
|   +----+-----+ +----+-----+ +----+-----+ +----+-----+ +----+----+   |
|        |            |            |            |            |        |
|        +------------+-----+------+------------+------------+        |
|                           |                                         |
|                           v                                         |
|  Summarization --> +------------------+ <-- Capabilities            |
|  Checkpointing --> |    Deep Agent    | <-- Hooks                   |
|  Cost Tracking --> |   (pydantic-ai)  | <-- Memory                  |
|                    +--------+---------+                             |
|                             |                                       |
|           +-----------------+-----------------+                     |
|           v                 v                 v                     |
|    +------------+    +------------+    +------------+               |
|    |   State    |    |   Local    |    |   Docker   |               |
|    |  Backend   |    |  Backend   |    |  Sandbox   |               |
|    +------------+    +------------+    +------------+               |
|                                                                     |
+---------------------------------------------------------------------+
```

---

## All Features

<details>
<summary><b>Click to expand full feature list</b></summary>

### Core Toolsets

- **Planning** -- Task tracking with subtasks, dependencies, cycle detection. PostgreSQL storage. Event system.
- **Filesystem** -- `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep`, `execute`. Docker sandbox. Permission system.
- **Subagents** -- Sync/async delegation. Background task management. Soft/hard cancellation.
- **Summarization** -- LLM-based summaries or zero-cost sliding window. Trigger on tokens, messages, or fraction.

### Capabilities

- **CostTracking** -- Token/USD budgets with automatic enforcement and real-time callbacks (from `pydantic-ai-shields`).
- **ContextManagerCapability** -- Auto-compression when approaching token budget (from `summarization-pydantic-ai`).
- **HooksCapability** -- Claude Code-style lifecycle hooks. Shell commands on tool events. Audit logging, safety gates.
- **CheckpointMiddleware** -- Save state at intervals. Rewind or fork sessions. In-memory and file-based stores. Extends `AbstractCapability`.
- **WebSearch / WebFetch** -- Built-in pydantic-ai capabilities for web search and URL fetching.
- **SkillsCapability** -- Domain-specific skills loaded from SKILL.md files.
- **ContextFilesCapability** -- Auto-discover and inject DEEP.md, AGENTS.md, CLAUDE.md, SOUL.md into the system prompt.
- **MemoryCapability** -- Persistent MEMORY.md across sessions, auto-injected into system prompt.
- **TeamCapability** -- Multi-agent teams with shared TODO lists, claiming, dependency tracking, and peer-to-peer message bus.
- **PlanCapability** -- Dedicated planner subagent for structured planning before execution.

### Advanced

- **Agent Teams** -- Shared TODO lists with claiming and dependency tracking. Peer-to-peer message bus.
- **Persistent Memory** -- `MEMORY.md` that persists across sessions. Auto-injected into system prompt.
- **Context Files** -- Auto-discover and inject `AGENT.md` into the system prompt.
- **Output Styles** -- Built-in (concise, explanatory, formal, conversational) or custom from files.
- **Plan Mode** -- Dedicated planner subagent for structured planning before execution.
- **Eviction Processor** -- Evict large tool outputs to files. Keep context lean while preserving data.
- **Patch Tool Calls** -- On resume, patch stale tool call results for clean history.
- **Custom Tool Descriptions** -- Override any tool's description via `descriptions` parameter.
- **Custom Commands** -- `/commit`, `/pr`, `/review`, `/test`, `/fix`, `/explain`. Three-scope discovery: built-in, user, project.
- **Structured Output** -- Type-safe responses with Pydantic models via `output_type`.
- **Human-in-the-Loop** -- Confirmation workflows for sensitive operations.
- **Streaming** -- Full streaming support for real-time responses.
- **Image Support** -- Multi-modal analysis with image inputs.

</details>

---

## Contributing

```bash
git clone https://github.com/vstorm-co/pydantic-deepagents.git
cd pydantic-deepagents
make install
make test  # 100% coverage required
make all   # lint + typecheck + test
```

---

## Star History

<p align="center">
  <a href="https://www.star-history.com/#vstorm-co/pydantic-deepagents&type=date">
    <img src="https://api.star-history.com/svg?repos=vstorm-co/pydantic-deepagents&type=date" alt="Star History" width="600">
  </a>
</p>

---

## License

MIT -- see [LICENSE](LICENSE)

---

<div align="center">

### Need help implementing this in your company?

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

<a href="https://vstorm.co/contact-us/">
  <img src="https://img.shields.io/badge/Talk%20to%20us%20%E2%86%92-0066FF?style=for-the-badge&logoColor=white" alt="Talk to us">
</a>

<br><br>

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

</div>
