(draft) 0.2.14 release

Author: DEENUU1

CHANGELOG.md

@@ -5,6 +5,47 @@ 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.1` dependency
+- 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
+
 ## [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
@@ -107,15 +116,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])
 ```
 

README.md

@@ -6,6 +6,8 @@
 
 > **Need just the backends?** Check out [pydantic-ai-backend](https://github.com/vstorm-co/pydantic-ai-backend) - file storage and sandbox backends that work with any pydantic-ai agent.
 
+> **Need just subagents?** Check out [subagents-pydantic-ai](https://github.com/vstorm-co/subagents-pydantic-ai) - task delegation toolset with dual-mode execution (sync/async).
+
 [![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)
@@ -41,7 +43,8 @@ pydantic-deep is built with modular, reusable components:
 |-----------|---------|-------------|
 | **Backends** | [pydantic-ai-backend](https://github.com/vstorm-co/pydantic-ai-backend) | File storage and Docker sandbox |
 | **Todo Toolset** | [pydantic-ai-todo](https://github.com/vstorm-co/pydantic-ai-todo) | Task planning and tracking |
-| **Summarization** | Built-in | Automatic context management* |
+| **Subagents** | [subagents-pydantic-ai](https://github.com/vstorm-co/subagents-pydantic-ai) | Task delegation with dual-mode execution |
+| **Summarization** | [summarization-pydantic-ai](https://github.com/vstorm-co/summarization-pydantic-ai) | Automatic context management* |
 
 *\*Note: Summarization will be added to pydantic-ai core in late January 2025 ([pydantic-ai#3780](https://github.com/pydantic/pydantic-ai/pull/3780)). We will migrate to use it once available.*
 
@@ -168,6 +171,8 @@ agent = create_deep_agent(history_processors=[processor])
 - **[pydantic-ai](https://github.com/pydantic/pydantic-ai)** - The foundation: Agent framework by Pydantic
 - **[pydantic-ai-backend](https://github.com/vstorm-co/pydantic-ai-backend)** - File storage and sandbox backends (extracted from pydantic-deep)
 - **[pydantic-ai-todo](https://github.com/vstorm-co/pydantic-ai-todo)** - Task planning toolset (extracted from pydantic-deep)
+- **[subagents-pydantic-ai](https://github.com/vstorm-co/subagents-pydantic-ai)** - Task delegation toolset (extracted from pydantic-deep)
+- **[summarization-pydantic-ai](https://github.com/vstorm-co/summarization-pydantic-ai)** - Context summarization (extracted from pydantic-deep)
 - **[fastapi-fullstack](https://github.com/vstorm-co/full-stack-fastapi-nextjs-llm-template)** - Full-stack AI app template with pydantic-deep
 
 ## Development

docs/advanced/processors.md

@@ -1,19 +1,21 @@
 # History Processors
 
-pydantic-deep supports history processors for managing conversation context. The most common use case is automatic summarization to handle long conversations without exceeding token limits.
+pydantic-deep supports history processors for managing conversation context. These processors are powered by [summarization-pydantic-ai](https://github.com/vstorm-co/summarization-pydantic-ai) and provide two strategies:
+
+- **SummarizationProcessor** - Intelligent LLM-based summarization
+- **SlidingWindowProcessor** - Zero-cost message trimming
 
 !!! info "Coming to pydantic-ai"
     This feature will be added to pydantic-ai core in late January 2025 ([pydantic-ai#3780](https://github.com/pydantic/pydantic-ai/pull/3780)). Once available, we will migrate to use the upstream implementation. The API will remain compatible.
 
 ## Summarization Processor
 
-The `SummarizationProcessor` monitors conversation length and automatically summarizes older messages when thresholds are reached.
+The `SummarizationProcessor` monitors conversation length and automatically summarizes older messages when thresholds are reached. This provides intelligent compression that preserves important context.
 
 ### Basic Usage
 
 ```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 a summarization processor
 processor = create_summarization_processor(
@@ -32,6 +34,8 @@ agent = create_deep_agent(
 You can trigger summarization based on different criteria:
 
 ```python
+from pydantic_deep import create_summarization_processor
+
 # Trigger when message count exceeds threshold
 processor = create_summarization_processor(
     trigger=("messages", 50),
@@ -62,6 +66,8 @@ processor = create_summarization_processor(
 Control how much context to keep after summarization:
 
 ```python
+from pydantic_deep import create_summarization_processor
+
 # Keep last N messages
 processor = create_summarization_processor(
     trigger=("tokens", 100000),
@@ -87,7 +93,10 @@ processor = create_summarization_processor(
 By default, the processor uses a simple character-based estimation (~4 characters per token). For more accurate counting, provide a custom token counter:
 
 ```python
-def count_tokens(messages):
+from pydantic_ai.messages import ModelMessage
+from pydantic_deep import create_summarization_processor
+
+def count_tokens(messages: list[ModelMessage]) -> int:
     """Custom token counter using tiktoken or similar."""
     import tiktoken
     enc = tiktoken.get_encoding("cl100k_base")
@@ -110,6 +119,8 @@ processor = create_summarization_processor(
 Customize how the summarization is performed:
 
 ```python
+from pydantic_deep import create_summarization_processor
+
 custom_prompt = """
 Extract the key information from this conversation.
 Focus on:
@@ -129,33 +140,110 @@ processor = create_summarization_processor(
 )
 ```
 
-## Using the Processor Class Directly
+## Sliding Window Processor
+
+The `SlidingWindowProcessor` provides a zero-cost alternative that simply discards old messages without LLM calls. This is useful when you don't need to preserve historical context.
+
+### Basic Usage
+
+```python
+from pydantic_deep import create_deep_agent, create_sliding_window_processor
+
+# Create a sliding window processor
+processor = create_sliding_window_processor(
+    trigger=("messages", 100),  # Trim when reaching 100 messages
+    keep=("messages", 50),      # Keep last 50 messages
+)
+
+# Create agent with the processor
+agent = create_deep_agent(
+    history_processors=[processor],
+)
+```
+
+### When to Use Sliding Window
+
+Choose `SlidingWindowProcessor` when:
+
+- **Cost matters**: No LLM calls for processing
+- **Speed matters**: Instant trimming without API latency
+- **Recent context is sufficient**: Tasks don't need historical information
+- **Conversations are long**: High-volume chat applications
 
-For more control, use `SummarizationProcessor` directly:
+Choose `SummarizationProcessor` when:
+
+- **Context preservation matters**: Need to remember earlier decisions
+- **Tasks span multiple topics**: Important details scattered throughout
+- **Quality over speed**: Willing to trade latency for better context
+
+### Configuration Examples
 
 ```python
-from pydantic_deep.processors import SummarizationProcessor
+from pydantic_deep import create_sliding_window_processor
 
-processor = SummarizationProcessor(
+# Message-based window
+processor = create_sliding_window_processor(
+    trigger=("messages", 100),
+    keep=("messages", 50),
+)
+
+# Token-based window
+processor = create_sliding_window_processor(
+    trigger=("tokens", 100000),
+    keep=("tokens", 50000),
+)
+
+# Fraction-based window
+processor = create_sliding_window_processor(
+    trigger=("fraction", 0.8),
+    keep=("fraction", 0.4),
+    max_input_tokens=200000,
+)
+```
+
+## Using Processor Classes Directly
+
+For more control, use the processor classes directly:
+
+```python
+from pydantic_deep import SummarizationProcessor, SlidingWindowProcessor
+
+# Summarization processor
+summarizer = SummarizationProcessor(
     model="openai:gpt-4.1",
     trigger=("tokens", 100000),
     keep=("messages", 20),
     max_input_tokens=None,
     trim_tokens_to_summarize=4000,  # Limit summary input size
 )
+
+# Sliding window processor
+window = SlidingWindowProcessor(
+    trigger=("tokens", 100000),
+    keep=("messages", 50),
+)
 ```
 
 ## How It Works
 
+### Summarization Processor
+
 1. **Before each model call**, the processor checks if any trigger condition is met
 2. If triggered, it finds a safe cutoff point that doesn't split tool call/response pairs
 3. Older messages are summarized using a lightweight LLM call
 4. The summary replaces the old messages, preserving recent context
 5. The agent continues with the compressed history
 
+### Sliding Window Processor
+
+1. **Before each model call**, the processor checks if any trigger condition is met
+2. If triggered, it finds a safe cutoff point that doesn't split tool call/response pairs
+3. Older messages are discarded (no LLM call)
+4. The agent continues with only recent messages
+
 ### Tool Call Safety
 
-The processor ensures tool calls and their responses stay together:
+Both processors ensure tool calls and their responses stay together:
 
 ```
 Messages: [User, AI+ToolCall, ToolResponse, User, AI+ToolCall, ToolResponse, User]
@@ -167,14 +255,17 @@ Messages: [User, AI+ToolCall, ToolResponse, User, AI+ToolCall, ToolResponse, Use
 You can chain multiple history processors:
 
 ```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,
+)
 
 # Multiple processors are applied in order
 agent = create_deep_agent(
     history_processors=[
         create_summarization_processor(trigger=("tokens", 100000)),
-        # Add more processors as needed
+        create_sliding_window_processor(trigger=("messages", 200)),
     ],
 )
 ```
@@ -189,6 +280,8 @@ agent = create_deep_agent(
 
 4. **Use fraction-based triggers for portability**: When switching between models with different context limits
 
+5. **Consider hybrid approaches**: Use summarization for important conversations and sliding window for casual chat
+
 ## Next Steps
 
 - [Structured Output](structured-output.md) - Type-safe responses with Pydantic models