Merge pull request #186 from vstorm-co/0.3.39

refactor: remove old folders and bump to 0.3.39

Author: DEENUU1

CHANGELOG.md

@@ -5,6 +5,21 @@ 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.3.39] - 2026-07-26
+
+The pre-`features/` import paths are gone.
+
+### Removed
+
+- **`pydantic_deep.toolsets`, `pydantic_deep.capabilities`, `pydantic_deep.processors` and `pydantic_deep.improve` are deleted** (`pydantic_deep/__init__.py`). Every feature moved into `pydantic_deep/features/<name>/` in 0.3.34, which said the old deep import paths would be removed in the next minor release; since then the four packages have been deprecation shims, re-exporting the moved names and warning on import. They are now removed — `features/` is the only import location.
+  - The blessed top-level surface is unchanged: `from pydantic_deep import SkillsToolset, HooksCapability, EvictionCapability, ...` still works, and `tests/test_public_api.py` (replacing `tests/test_feature_shims.py`) asserts each re-export is the same object as the one in its feature package.
+  - Deep imports must move to the feature package: `pydantic_deep.toolsets.memory` → `pydantic_deep.features.memory`, `pydantic_deep.capabilities.hooks` → `pydantic_deep.features.hooks`, `pydantic_deep.processors.eviction` → `pydantic_deep.features.eviction`, `pydantic_deep.improve` → `pydantic_deep.features.improve`, and likewise for `context`, `browser`, `skills`, `plan`, `teams`, `forking`, `checkpointing`, `liteparse`, `patch`, `history_archive`, `message_queue`, `stuck_loop`, `periodic_reminder`.
+  - Logger names follow the modules: code filtering on `pydantic_deep.capabilities.hooks` or `pydantic_deep.capabilities.periodic_reminder` should now use `pydantic_deep.features.hooks.capability` / `pydantic_deep.features.periodic_reminder.capability`.
+
+### Fixed
+
+- **`examples/skills_usage.py` discovery demos run again** (`examples/skills_usage.py`). `--discover` and `--load` imported `discover_skills` / `load_skill_instructions`, which stopped existing well before the reorg, so both modes died on `ImportError`. They now use `SkillsDirectory.get_skills()` and read `Skill` attributes instead of dict keys.
+
 ## [0.3.38] - 2026-07-24
 
 MCP resources and skills reach the model, the CLI talks to any

CLAUDE.md

@@ -24,8 +24,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - `pydantic_deep/` — Core library (agent, deps, models, instructions, types)
 - `pydantic_deep/features/<name>/` — One vertical-slice package per feature
   (`capability.py` + `toolset.py` + `service.py`/`types.py`). Organize by
-  feature, not by kind. The old `toolsets/`, `capabilities/`, and `processors/`
-  paths now hold deprecation shims that re-export from `features/`.
+  feature, not by kind — `features/` is the only import location; the old
+  `toolsets/`, `capabilities/`, `processors/` and `improve/` shims were removed
+  in 0.3.39.
 - `apps/cli/` — CLI + TUI application (Textual-based terminal AI assistant)
 - `apps/deepresearch/` — Full-featured research reference app
 - `tests/` — Unit tests
@@ -50,7 +51,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - `DockerSandbox`: Isolated Docker container execution
 - `CompositeBackend`: Combines multiple backends with routing
 
-**Toolsets (`pydantic_deep/toolsets/`)**
+**Toolsets (`pydantic_deep/features/<name>/toolset.py`)**
 - `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 - from [subagents-pydantic-ai](https://github.com/vstorm-co/subagents-pydantic-ai)
@@ -114,12 +115,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - Hook methods: `before_tool_execute`, `after_tool_execute`, `on_tool_execute_error`
 - `EXIT_ALLOW = 0`, `EXIT_DENY = 2`: Claude Code exit code conventions
 
-**Capabilities (`pydantic_deep/capabilities/`)**
+**Capabilities (`pydantic_deep/features/<name>/capability.py`)**
 - `SkillsCapability`: Injects skills system prompt and manages skill discovery
 - `ContextFilesCapability`: Auto-discovers and injects context files (DEEP.md, AGENTS.md, CLAUDE.md, SOUL.md)
 - `MemoryCapability`: Persistent memory management with read/write/update tools
-- `TeamCapability`: Agent team coordination and management
-- `PlanCapability`: Planning mode with ask_user + save_plan tools
+- `BrowserCapability`, `StuckLoopDetection`, `PeriodicReminderCapability`,
+  `HooksCapability`, `EvictionCapability`, `PatchToolCallsCapability`
 - All extend pydantic-ai's `AbstractCapability`
 
 **Persistent Memory (`pydantic_deep/features/memory/`)**
@@ -235,7 +236,7 @@ agent = create_deep_agent(
 ```python
 from pydantic_deep import create_deep_agent
 from pydantic_ai_shields import CostTracking
-from pydantic_deep.capabilities.hooks import HooksCapability, Hook, HookEvent
+from pydantic_deep.features.hooks import HooksCapability, Hook, HookEvent
 
 agent = create_deep_agent(
     model="anthropic:claude-sonnet-4-6",

docs/api/capabilities.md

@@ -9,31 +9,31 @@ conceptual overview.
 
 ## SkillsCapability
 
-::: pydantic_deep.capabilities.SkillsCapability
+::: pydantic_deep.features.skills.SkillsCapability
     options:
       show_source: false
 
 ## ContextFilesCapability
 
-::: pydantic_deep.capabilities.ContextFilesCapability
+::: pydantic_deep.features.context.ContextFilesCapability
     options:
       show_source: false
 
 ## MemoryCapability
 
-::: pydantic_deep.capabilities.MemoryCapability
+::: pydantic_deep.features.memory.MemoryCapability
     options:
       show_source: false
 
 ## BrowserCapability
 
-::: pydantic_deep.capabilities.BrowserCapability
+::: pydantic_deep.features.browser.BrowserCapability
     options:
       show_source: false
 
 ## StuckLoopDetection
 
-::: pydantic_deep.capabilities.StuckLoopDetection
+::: pydantic_deep.features.stuck_loop.StuckLoopDetection
     options:
       show_source: false
 
@@ -43,7 +43,7 @@ conceptual overview.
 
 ## PeriodicReminderCapability
 
-::: pydantic_deep.capabilities.PeriodicReminderCapability
+::: pydantic_deep.features.periodic_reminder.PeriodicReminderCapability
     options:
       show_source: false
 

docs/api/index.md

@@ -8,9 +8,9 @@ Complete API documentation for pydantic-deep.
 |--------|-------------|
 | [`pydantic_deep.agent`](agent.md) | Agent factory and configuration |
 | [Backends](backends.md) | Storage backends (via [pydantic-ai-backend](https://github.com/vstorm-co/pydantic-ai-backend)) |
-| [`pydantic_deep.toolsets`](toolsets.md) | Tool collections |
-| [`pydantic_deep.capabilities`](capabilities.md) | Lifecycle capabilities |
-| [`pydantic_deep.processors`](processors.md) | History processors |
+| [Toolsets](toolsets.md) | Tool collections |
+| [Capabilities](capabilities.md) | Lifecycle capabilities |
+| [Processors](processors.md) | History processors |
 | [`pydantic_deep.mcp`](mcp.md) | MCP client support |
 | [Forking](forking.md) | Live Run Forking (parallel branches) |
 | [`pydantic_deep.spec`](spec.md) | Declarative agent specs (YAML/JSON) |
@@ -60,7 +60,7 @@ from pydantic_deep import (
 # Toolsets (from their respective packages)
 from pydantic_ai_backends import create_console_toolset
 from pydantic_ai_todo import create_todo_toolset
-from pydantic_deep.toolsets import SubAgentToolset, SkillsToolset
+from pydantic_deep import SubAgentToolset, SkillsToolset
 ```
 
 ### Creating an Agent

docs/c4/2-architecture-overview.md

@@ -598,32 +598,32 @@ flowchart LR
 | **Dependencies** | BackendProtocol, UploadedFile, FileData, Todo types |
 | **Location** | `pydantic_deep/deps.py` |
 
-### Module: Toolsets (`toolsets/`)
+### Module: Toolsets (`features/*/toolset.py`)
 
 | Attribute | Details |
 |-----------|---------|
 | **Purpose** | Provide tools the agent can call |
 | **Key Components** | 9 toolsets spanning planning, filesystem, subagents, skills, checkpoints, memory, teams |
 | **Dependencies** | pydantic-ai FunctionToolset, pydantic-ai-backend, pydantic-ai-todo, subagents-pydantic-ai |
-| **Location** | `pydantic_deep/toolsets/` |
+| **Location** | `pydantic_deep/features/<name>/toolset.py` |
 
-### Module: Capabilities (`capabilities/`)
+### Module: Capabilities (`features/*/capability.py`)
 
 | Attribute | Details |
 |-----------|---------|
 | **Purpose** | Wrap toolsets into pydantic-ai's capability interface |
 | **Key Components** | 6 capabilities, each a thin adapter layer |
-| **Dependencies** | toolsets.*, pydantic-ai AbstractCapability |
-| **Location** | `pydantic_deep/capabilities/` |
+| **Dependencies** | features.*, pydantic-ai AbstractCapability |
+| **Location** | `pydantic_deep/features/<name>/capability.py` |
 
-### Module: Processors (`processors/`)
+### Module: Processors (`features/{eviction,patch,history_archive}/`)
 
 | Attribute | Details |
 |-----------|---------|
 | **Purpose** | Transform message history before sending to LLM |
 | **Key Components** | 2 processors + 1 search toolset |
 | **Dependencies** | pydantic-ai messages, pydantic-ai-backend BackendProtocol |
-| **Location** | `pydantic_deep/processors/` |
+| **Location** | `pydantic_deep/features/{eviction,patch,history_archive}/` |
 
 ---
 
@@ -651,4 +651,4 @@ flowchart LR
 
 ---
 
-*This architecture documentation follows the C4 model for visualizing software architecture. For implementation details, refer to the source code and API documentation.*
+*This architecture documentation follows the C4 model for visualizing software architecture. For implementation details, refer to the source code and API documentation.*

docs/c4/4b-deep-dive-toolsets-and-capabilities.md

@@ -480,7 +480,7 @@ Wraps `AgentMemoryToolset` with both tools and instruction injection.
 
 ### 4. PlanCapability
 
-**Source:** `pydantic_deep/capabilities/plan.py`
+**Source:** `pydantic_deep/features/plan/`
 
 Wraps `create_plan_toolset()` providing `ask_user` and `save_plan` tools.
 
@@ -507,7 +507,7 @@ Wraps `SkillsToolset` with skill discovery, loading, and instruction injection.
 
 ### 6. TeamCapability
 
-**Source:** `pydantic_deep/capabilities/teams.py`
+**Source:** `pydantic_deep/features/teams/`
 
 Wraps `create_team_toolset()` for multi-agent coordination.
 
@@ -915,4 +915,4 @@ class XxxCapability(AbstractCapability[Any]):
 | MemoryCapability | Yes | Yes |
 | PlanCapability | Yes | No |
 | SkillsCapability | Yes | Yes |
-| TeamCapability | Yes | No |
+| TeamCapability | Yes | No |

docs/concepts/agents.md

@@ -299,7 +299,7 @@ See [Structured Output](../learn/structured-output.md) for more details.
 Automatically summarize long conversations:
 
 ```python
-from pydantic_deep.processors import create_summarization_processor
+from pydantic_deep import create_summarization_processor
 
 processor = create_summarization_processor(
     trigger=("tokens", 100000),

examples/security_gate/README.md

@@ -1,6 +1,6 @@
 # Security Gate Example
 
-Demonstrates [`default_security_hook()`][pydantic_deep.capabilities.hooks.default_security_hook] —
+Demonstrates [`default_security_hook()`][pydantic_deep.features.hooks.default_security_hook] —
 the built-in safety preset that blocks destructive commands, path-traversal
 writes, and credential reads, plus redacts secret-shaped tokens from tool output.
 

examples/security_gate/main.py

@@ -10,7 +10,7 @@
 import asyncio
 
 from pydantic_deep import default_security_hook
-from pydantic_deep.capabilities.hooks import DEFAULT_BLOCKED_COMMANDS, HookEvent, HookInput
+from pydantic_deep.features.hooks import DEFAULT_BLOCKED_COMMANDS, HookEvent, HookInput
 
 
 def _pre_input(tool_name: str, args: dict[str, object]) -> HookInput:

examples/skills_usage.py

@@ -101,38 +101,35 @@ def get_user_data(user_id):
 
 
 async def demo_skill_discovery():
-    """Demonstrate skill discovery from multiple directories."""
-    from pydantic_deep.toolsets.skills import discover_skills
+    """Demonstrate skill discovery from a directory."""
+    from pydantic_deep.features.skills import SkillsDirectory
 
     print("Discovering skills from:", SKILLS_DIR)
     print()
 
-    skills = discover_skills([{"path": str(SKILLS_DIR), "recursive": True}])
-
-    for skill in skills:
-        print(f"Skill: {skill['name']}")
-        print(f"  Description: {skill['description']}")
-        print(f"  Version: {skill['version']}")
-        print(f"  Tags: {', '.join(skill['tags'])}")
-        print(f"  Path: {skill['path']}")
-        if skill.get("resources"):
-            print(f"  Resources: {', '.join(skill['resources'])}")
+    for uri, skill in SkillsDirectory(path=SKILLS_DIR).get_skills().items():
+        print(f"Skill: {skill.name}")
+        print(f"  Description: {skill.description}")
+        print(f"  URI: {uri}")
+        if skill.resources:
+            print(f"  Resources: {', '.join(r.name for r in skill.resources)}")
+        if skill.scripts:
+            print(f"  Scripts: {', '.join(s.name for s in skill.scripts)}")
         print()
 
 
 async def demo_skill_loading():
     """Demonstrate loading full skill instructions."""
-    from pydantic_deep.toolsets.skills import discover_skills, load_skill_instructions
+    from pydantic_deep.features.skills import SkillsDirectory
 
-    skills = discover_skills([{"path": str(SKILLS_DIR), "recursive": True}])
+    skills = list(SkillsDirectory(path=SKILLS_DIR).get_skills().values())
 
     if skills:
         skill = skills[0]
-        print(f"Loading full instructions for: {skill['name']}")
+        print(f"Loading full instructions for: {skill.name}")
         print("=" * 60)
 
-        instructions = load_skill_instructions(skill["path"])
-        print(instructions[:500] + "..." if len(instructions) > 500 else instructions)
+        print(skill.content[:500] + "..." if len(skill.content) > 500 else skill.content)
 
 
 if __name__ == "__main__":