forked from cleveragents/cleveragents-core
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
102 lines
3.1 KiB
Markdown
102 lines
3.1 KiB
Markdown
# `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/ADR-008-resource-system.md),
|
|
[ADR-036](../adr/ADR-036-resource-dag-operational-semantics.md), and
|
|
[ADR-042](../adr/ADR-042-resource-type-inheritance.md) 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).
|
|
|
|
```python
|
|
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`.
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
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: ...
|
|
```
|