(draft) 0.2.14 release

CHANGELOG.md

@@ -5,6 +5,55 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.14] - 2025-01-21
+
+### Changed
+
+- **Breaking:** Removed local `pydantic_deep/processors/` module - now uses external [summarization-pydantic-ai](https://github.com/vstorm-co/summarization-pydantic-ai) library
+- **Breaking:** Removed local `pydantic_deep/toolsets/subagents.py` module - now uses external [subagents-pydantic-ai](https://github.com/vstorm-co/subagents-pydantic-ai) library
+- Added `summarization-pydantic-ai>=0.0.1` dependency
+- Added `subagents-pydantic-ai>=0.0.3` dependency (fixed docs imports)
+- Updated `pydantic-ai-todo>=0.1.5` dependency (added missing exports)
+- Updated `summarization-pydantic-ai>=0.0.2` dependency (new documentation site)
+- Updated `pydantic-ai-backend>=0.1.4` dependency (new documentation site)
+- Re-exported `SummarizationProcessor`, `SlidingWindowProcessor`, `create_summarization_processor`, `create_sliding_window_processor` from summarization-pydantic-ai
+- Re-exported `SubAgentToolset`, `create_subagent_toolset`, `get_subagent_system_prompt` from subagents-pydantic-ai
+- Re-exported `SubAgentConfig`, `CompiledSubAgent` types from subagents-pydantic-ai
+- Updated `DeepAgentDeps.clone_for_subagent()` to accept optional `max_depth` parameter for nested subagent support
+
+### Added
+
+- `SlidingWindowProcessor` - zero-cost message trimming without LLM calls (new from summarization-pydantic-ai)
+- `create_sliding_window_processor()` - factory function for sliding window processors
+- **Dual-mode execution**: Subagents can now run in sync (blocking) or async (background) modes
+- **Auto mode**: Intelligent mode selection based on task characteristics
+- **Task management tools**: `check_task`, `list_active_tasks`, `soft_cancel_task`, `hard_cancel_task`
+- **Subagent communication**: `ask_parent` tool for subagents to query the parent agent
+- **Dynamic agent creation**: Runtime agent creation via `create_agent_factory_toolset`
+- New types: `TaskHandle`, `TaskStatus`, `TaskPriority`, `TaskCharacteristics`, `ExecutionMode`
+
+### Fixed
+
+- Added `chardet>=5.0.0` dependency back - was incorrectly removed in 0.2.13 but is still needed for `DeepAgentDeps.upload_file()` encoding detection ([#22](https://github.com/vstorm-co/pydantic-deep/issues/22))
+- Subagents now automatically get `console_toolset` and `todo_toolset` like in previous versions - the migration to `subagents-pydantic-ai` accidentally removed these default tools ([#21](https://github.com/vstorm-co/pydantic-deep/issues/21))
+
+### Documentation
+
+- Updated `docs/advanced/processors.md` with SlidingWindowProcessor documentation
+- Updated `docs/api/processors.md` with full API reference for both processors
+- Updated `CLAUDE.md` with new processor imports and subagent imports from external packages
+- Updated `README.md` with subagents-pydantic-ai references in modular architecture
+- Updated `docs/advanced/subagents.md` with dual-mode execution and new SubAgentConfig fields
+- Updated `docs/api/toolsets.md` with complete SubAgentToolset API including task management tools
+- Updated `docs/api/types.md` with new subagent types (TaskHandle, TaskStatus, TaskPriority, ExecutionMode)
+- Updated `docs/examples/subagents.md` with correct tool names and updated SubAgentConfig example
+- Updated `docs/concepts/toolsets.md` with SubAgentToolset tools and correct parameter names
+- Fixed `CLAUDE.md` - corrected `LocalBackend(root=...)` to `LocalBackend(root_dir=...)`
+- Fixed `CLAUDE.md` - corrected `CompositeBackend` API signature (uses `default` and `routes`, not `backends`)
+- Fixed `README.md` - corrected import path `pydantic_deep.processors` to `pydantic_deep`
+- Fixed `docs/api/agent.md` - added missing `include_execute` parameter to signature and parameters table
+- Fixed `pydantic_deep/agent.py` - corrected docstring model default from "Claude Sonnet 4" to "openai:gpt-4.1"
+
 ## [0.2.13] - 2025-01-17
 
 ### Changed

CLAUDE.md

@@ -40,12 +40,21 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 **Toolsets (`pydantic_deep/toolsets/`)**
 - `TodoToolset`: Task planning and tracking tools (read_todos, write_todos) - from [pydantic-ai-todo](https://github.com/vstorm-co/pydantic-ai-todo)
 - `create_console_toolset`: File operations (ls, read, write, edit, glob, grep, execute) - from [pydantic-ai-backend](https://github.com/vstorm-co/pydantic-ai-backend)
-- `SubAgentToolset`: Spawn and delegate to subagents
+- `SubAgentToolset`: Spawn and delegate to subagents - from [subagents-pydantic-ai](https://github.com/vstorm-co/subagents-pydantic-ai)
 - `SkillsToolset`: Load and use skill definitions from markdown files
 
-**Processors (`pydantic_deep/processors/`)**
-- `SummarizationProcessor`: Automatic conversation summarization for token management
-- `create_summarization_processor()`: Factory function for creating summarization processors
+**Subagents (from [subagents-pydantic-ai](https://github.com/vstorm-co/subagents-pydantic-ai))**
+- `create_subagent_toolset()`: Factory function to create subagent toolsets
+- `get_subagent_system_prompt()`: Generate system prompt for subagent tools
+- Dual-mode execution: sync (blocking) or async (background)
+- Task management: check_task, list_active_tasks, soft_cancel_task, hard_cancel_task
+- Types: `SubAgentConfig`, `CompiledSubAgent`, `TaskHandle`, `TaskStatus`, `TaskPriority`
+
+**Processors (from [summarization-pydantic-ai](https://github.com/vstorm-co/summarization-pydantic-ai))**
+- `SummarizationProcessor`: LLM-based conversation summarization for token management
+- `SlidingWindowProcessor`: Zero-cost message trimming without LLM calls
+- `create_summarization_processor()`: Factory function for summarization processors
+- `create_sliding_window_processor()`: Factory function for sliding window processors
 
 **Types (`pydantic_deep/types.py`)**
 - Pydantic models for all data structures
@@ -64,10 +73,15 @@ from pydantic_ai_backends import StateBackend, LocalBackend, CompositeBackend
 backend = StateBackend()
 
 # Real filesystem
-backend = LocalBackend(root="/path/to/workspace")
-
-# Combined backends
-backend = CompositeBackend(backends=[StateBackend(), LocalBackend()])
+backend = LocalBackend(root_dir="/path/to/workspace")
+
+# Combined backends with routing
+backend = CompositeBackend(
+    default=StateBackend(),
+    routes={
+        "/project/": LocalBackend(root_dir="/home/user/project"),
+    },
+)
 ```
 
 **Toolset Registration**
@@ -107,15 +121,24 @@ agent = create_deep_agent(output_type=TaskResult)
 
 **Context Management / Summarization**
 ```python
-from pydantic_deep import create_deep_agent
-from pydantic_deep.processors import create_summarization_processor
+from pydantic_deep import (
+    create_deep_agent,
+    create_summarization_processor,
+    create_sliding_window_processor,
+)
 
 # Automatically summarize when reaching token limits
 processor = create_summarization_processor(
     trigger=("tokens", 100000),  # or ("messages", 50) or ("fraction", 0.8)
     keep=("messages", 20),       # Keep last N messages after summarization
 )
 
+# Or use sliding window for zero-cost trimming
+window = create_sliding_window_processor(
+    trigger=("messages", 100),
+    keep=("messages", 50),
+)
+
 agent = create_deep_agent(history_processors=[processor])
 ```
 

CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Contributing to pydantic-deep
+
+Thanks for your interest in contributing!
+
+## Development Setup
+
+```bash
+git clone https://github.com/vstorm-co/pydantic-deepagents.git
+cd pydantic-deepagents
+make install
+```
+
+## Running Tests
+
+```bash
+make test        # Run tests with coverage
+make all         # Run lint + typecheck + test
+```
+
+## Requirements
+
+All PRs must meet these requirements:
+
+- **100% test coverage** — no exceptions
+- **Pass Pyright** — `make typecheck`
+- **Pass MyPy** — `make typecheck-mypy`
+- **Pass Ruff** — `make lint`
+
+## Quick Commands
+
+| Command | Description |
+|---------|-------------|
+| `make install` | Install dependencies |
+| `make test` | Run tests with coverage |
+| `make lint` | Run Ruff linter |
+| `make typecheck` | Run Pyright |
+| `make typecheck-mypy` | Run MyPy |
+| `make all` | Run all checks |
+| `make docs-serve` | Serve docs locally |
+
+## Running Specific Tests
+
+```bash
+# Single test
+uv run pytest tests/test_agent.py::test_function_name -v
+
+# Single file
+uv run pytest tests/test_agent.py -v
+
+# With debug output
+uv run pytest tests/test_agent.py -v -s
+```
+
+## Code Style
+
+- We use [Ruff](https://github.com/astral-sh/ruff) for linting and formatting
+- Run `make lint` to check and `uv run ruff format .` to auto-format
+- Follow existing patterns in the codebase
+
+## Pull Request Process
+
+1. Fork the repo and create your branch from `main`
+2. Make your changes
+3. Ensure `make all` passes
+4. Submit a PR with a clear description
+
+## Questions?
+
+Open an issue on [GitHub](https://github.com/vstorm-co/pydantic-deepagents/issues).