cleveragents-core/docs/api/resource.md

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: ...