freemo
e9c96c3d0c
Add docs/api/ with per-module API documentation for core, a2a, actor, skills, tool, mcp, resource, and config packages. Add docs/architecture.md with a developer-oriented system overview including component map, layer diagram, plan lifecycle, and key design decisions. Update mkdocs.yml nav to expose both new sections. ISSUES CLOSED: #N/A
3.1 KiB
cleveragents.resource — Resource System
The resource package provides the resource type schema, handler
infrastructure, and the type-inheritance resolution system. Resources
are the managed external entities (files, databases, containers, LSP
servers, cloud services) that plans read from and write to.
See ADR-008, ADR-036, and ADR-042 for design rationale.
Type Inheritance
resolve_inheritance_chain(type_name, registry) → list[str]
Returns the full inheritance chain for a resource type, from the type
itself up to the root. Raises ResourceTypeCircularInheritanceError if
a cycle is detected, or ResourceTypeInheritanceDepthError if the chain
exceeds MAX_CHAIN_DEPTH (default: 16).
from cleveragents.resource import resolve_inheritance_chain
chain = resolve_inheritance_chain("container.docker", registry)
# → ["container.docker", "container", "resource"]
resolve_fields(type_name, registry) → dict[str, Any]
Merges field definitions from the full inheritance chain, with child fields overriding parent fields.
is_subtype_of(child, parent, registry) → bool
Returns True if child is a subtype of parent.
from cleveragents.resource import is_subtype_of
is_subtype_of("container.docker", "container", registry) # True
find_subtypes(parent, registry) → list[str]
Returns all registered types that are subtypes of parent.
validate_chain(chain) → None
Validates a pre-computed inheritance chain for cycles and depth.
TypeRegistryMap
Type alias: dict[str, ResourceTypeDefinition]. The registry maps type
names to their definitions.
Inheritance Errors
| Exception | Description |
|---|---|
ResourceTypeCircularInheritanceError |
Cycle detected in type hierarchy |
ResourceTypeInheritanceDepthError |
Chain exceeds MAX_CHAIN_DEPTH |
ResourceTypeParentNotFoundError |
Parent type not registered |
ResourceTypeParentRemovalError |
Attempt to remove a type that has children |
Constants
| Constant | Value | Description |
|---|---|---|
MAX_CHAIN_DEPTH |
16 |
Maximum inheritance chain depth |
Resource Handlers
Resource handlers live in cleveragents.resource.handlers and implement
CRUD, checkpoint, and rollback operations for specific resource types.
Built-in handlers include:
| Handler | Resource Types |
|---|---|
| Database handler | sqlite, postgresql, mysql, duckdb |
| Container handler | container.docker, container.podman |
| LSP handler | lsp.* |
| File handler | file, directory |
| Cloud handler | cloud.* |
Each handler implements the ResourceHandler protocol:
class ResourceHandler(Protocol):
async def read(self, resource_id: str, context: ...) -> Any: ...
async def write(self, resource_id: str, data: Any, context: ...) -> None: ...
async def checkpoint(self, resource_id: str) -> str: ...
async def rollback(self, resource_id: str, checkpoint_id: str) -> None: ...