tools-only Types API
All type definitions used in pydantic-deep.
File Types
FileData
Storage format for file contents.
class FileData(TypedDict):
content: list[str] # Lines of the file
created_at: str # ISO 8601 timestamp
modified_at: str # ISO 8601 timestamp
FileInfo
File metadata for listings.
class FileInfo(TypedDict):
name: str # File or directory name
path: str # Full path
is_dir: bool # True if directory
size: int | None # File size in bytes (None for directories)
UploadedFile
Metadata for uploaded files (from deps.upload_file()).
class UploadedFile(TypedDict):
path: str # Path where file was stored (e.g., "/uploads/data.csv")
original_name: str # Original filename
size: int # File size in bytes
line_count: int | None # Number of lines (None for binary files)
mime_type: str # Detected MIME type (e.g., "text/csv")
encoding: str | None # Detected encoding (e.g., "utf-8", None for binary)
Usage:
from pydantic_deep import DeepAgentDeps, StateBackend
deps = DeepAgentDeps(backend=StateBackend())
# Upload a file
deps.upload_file("report.csv", csv_bytes)
# Access upload metadata
for path, info in deps.uploads.items():
print(f"File: {info['original_name']}")
print(f"Size: {info['size']} bytes")
print(f"Lines: {info['line_count']}")
print(f"Type: {info['mime_type']}")
Operation Results
WriteResult
Result of write operations.
@dataclass
class WriteResult:
path: str | None = None # Path where file was written
error: str | None = None # Error message if failed
EditResult
Result of edit operations.
@dataclass
class EditResult:
path: str | None = None # Path of edited file
error: str | None = None # Error message if failed
occurrences: int | None = None # Number of replacements made
ExecuteResponse
Result of command execution.
@dataclass
class ExecuteResponse:
output: str # stdout + stderr
exit_code: int | None = None # Process exit code
truncated: bool = False # True if output was truncated
GrepMatch
Single grep match result.
class GrepMatch(TypedDict):
path: str # File path
line_number: int # Line number (1-indexed)
line: str # Matching line content
Todo Types
Todo
Task item for planning.
class Todo(BaseModel):
content: str # Task description
status: Literal["pending", "in_progress", "completed"]
active_form: str # Present continuous form (e.g., "Implementing feature")
Status Values:
| Status | Description |
|---|---|
pending |
Not yet started |
in_progress |
Currently working on |
completed |
Done |
Subagent Types
These types are provided by subagents-pydantic-ai.
SubAgentConfig
Configuration for a subagent.
class SubAgentConfig(TypedDict, total=False):
# Required fields
name: str # Unique identifier
description: str # When to use this subagent
instructions: str # System prompt for subagent
# Optional fields
model: NotRequired[str] # Custom model (overrides default)
can_ask_questions: NotRequired[bool] # Enable ask_parent tool
max_questions: NotRequired[int] # Max questions per task
preferred_mode: NotRequired[Literal["sync", "async", "auto"]] # Execution preference
typical_complexity: NotRequired[Literal["simple", "moderate", "complex"]]
typically_needs_context: NotRequired[bool]
toolsets: NotRequired[list[Any]] # Additional toolsets
agent_kwargs: NotRequired[dict[str, Any]] # Additional Agent kwargs
CompiledSubAgent
Pre-compiled subagent ready for use.
@dataclass
class CompiledSubAgent:
name: str # Unique identifier
description: str # Brief description
config: SubAgentConfig # Original configuration
agent: object | None # Agent instance
ExecutionMode
Execution mode for subagent tasks.
ExecutionMode = Literal["sync", "async", "auto"]
- sync: Execute synchronously, blocking until completion (default)
- async: Execute in background, return immediately with task handle
- auto: Automatically decide based on task characteristics
TaskStatus
Status of a background task.
class TaskStatus(str, Enum):
PENDING = "pending" # Task is queued
RUNNING = "running" # Currently executing
WAITING_FOR_ANSWER = "waiting_for_answer" # Blocked on question
COMPLETED = "completed" # Finished successfully
FAILED = "failed" # Failed with error
CANCELLED = "cancelled" # Was cancelled
TaskPriority
Priority levels for background tasks.
class TaskPriority(str, Enum):
LOW = "low"
NORMAL = "normal"
HIGH = "high"
CRITICAL = "critical"
TaskHandle
Handle for managing a background task.
@dataclass
class TaskHandle:
task_id: str # Unique identifier
subagent_name: str # Name of executing subagent
description: str # Task description
status: TaskStatus # Current status
priority: TaskPriority # Task priority
created_at: datetime # When created
started_at: datetime | None # When started
completed_at: datetime | None # When finished
result: str | None # Result (if completed)
error: str | None # Error (if failed)
pending_question: str | None # Question waiting for answer
Skill Types
Skill
Complete skill definition.
class Skill(TypedDict):
name: str # Unique identifier
description: str # Brief description
path: str # Path to skill directory
tags: list[str] # Categorization tags
version: str # Semantic version
author: str # Skill author
frontmatter_loaded: bool # True if only frontmatter loaded
instructions: NotRequired[str] # Full instructions (loaded on demand)
resources: NotRequired[list[str]] # Additional files in skill directory
SkillDirectory
Configuration for skill discovery.
class SkillDirectory(TypedDict):
path: str # Path to skills directory
recursive: NotRequired[bool] # Search recursively (default: True)
SkillFrontmatter
YAML frontmatter from SKILL.md.
class SkillFrontmatter(TypedDict):
name: str
description: str
tags: NotRequired[list[str]]
version: NotRequired[str]
author: NotRequired[str]
Usage Examples
Creating a Todo
from pydantic_deep import Todo
todo = Todo(
content="Implement authentication",
status="in_progress",
active_form="Implementing authentication",
)
Creating a SubAgentConfig
from pydantic_deep import SubAgentConfig
config: SubAgentConfig = {
"name": "code-reviewer",
"description": "Reviews code for quality and security",
"instructions": "You are an expert code reviewer...",
}
Creating a Skill
from pydantic_deep import Skill
skill: Skill = {
"name": "api-design",
"description": "Design RESTful APIs",
"path": "/path/to/skill",
"tags": ["api", "rest"],
"version": "1.0.0",
"author": "your-name",
"frontmatter_loaded": True,
}
Creating a SkillDirectory
from pydantic_deep import SkillDirectory
dirs: list[SkillDirectory] = [
{"path": "~/.pydantic-deep/skills", "recursive": True},
{"path": "./project-skills", "recursive": False},
]
Team Types
SharedTodoItem
Task item for team-shared task management.
@dataclass
class SharedTodoItem:
id: str # Auto-generated (uuid4 hex[:8])
content: str = ""
status: str = "pending" # pending | in_progress | completed
assigned_to: str | None = None
blocked_by: list[str] = []
created_by: str | None = None
TeamMessage
Message between team members.
@dataclass
class TeamMessage:
id: str # Auto-generated (uuid4 hex[:8])
sender: str = ""
receiver: str = "" # Empty = broadcast
content: str = ""
timestamp: datetime
TeamMember
Member of an agent team.
@dataclass
class TeamMember:
name: str
role: str
description: str
instructions: str
model: str = "openai:gpt-4.1"
toolsets: list[Any] = []
Checkpoint Types
Checkpoint
Immutable snapshot of conversation state.
@dataclass
class Checkpoint:
id: str # UUID4
label: str # Human-readable label
turn: int # Model-request counter
messages: list[ModelMessage] # Conversation snapshot
message_count: int
created_at: datetime
metadata: dict[str, Any] = {}
Hook Types
Hook
Hook definition for tool lifecycle events.
@dataclass
class Hook:
event: HookEvent # PRE_TOOL_USE | POST_TOOL_USE | POST_TOOL_USE_FAILURE
command: str | None = None # Shell command
handler: Callable | None = None # Async Python function
matcher: str | None = None # Regex pattern for tool_name
timeout: int = 30
background: bool = False
HookEvent
class HookEvent(str, Enum):
PRE_TOOL_USE = "pre_tool_use"
POST_TOOL_USE = "post_tool_use"
POST_TOOL_USE_FAILURE = "post_tool_use_failure"
Style Types
OutputStyle
Output style definition.
@dataclass
class OutputStyle:
name: str # Style identifier
description: str # Brief description
content: str # Instructions for system prompt
Memory Types
MemoryFile
Loaded agent memory file.
@dataclass
class MemoryFile:
agent_name: str # "main", "code-reviewer", etc.
path: str # Full path in backend
content: str # Memory file content
Context Types
ContextFile
Loaded project context file.
@dataclass
class ContextFile:
name: str # Filename: "DEEP.md"
path: str # Full path: "/project/DEEP.md"
content: str # File content
Type Checking
All types support runtime checking:
from pydantic_deep import Skill
def process_skill(skill: Skill) -> None:
# Type checker knows all fields
print(skill["name"])
print(skill["description"])
# Optional fields
if "instructions" in skill:
print(skill["instructions"])
Types are exported from the main module:
from pydantic_deep import (
FileData,
FileInfo,
UploadedFile,
WriteResult,
EditResult,
ExecuteResponse,
GrepMatch,
Todo,
SubAgentConfig,
CompiledSubAgent,
Skill,
SkillDirectory,
SkillFrontmatter,
)