Capabilities¶

Register and invoke sync capability handlers.

Auto-generated docs

When trails is installed, run ENABLE_MKDOCSTRINGS=true ./scripts/docs-build for full docstring-extracted reference.

Registration¶

Symbol	Signature	Description
`@capability`	`@capability(_fn_or_id=None, *, id: str \\| None = None, name: str \\| None = None, description: str = "", input_shape: str \\| None = None, output_shape: str \\| None = None, preconditions: list[str] \\| None = None, idempotent: bool = False)`	Register a function as a sync Trails capability. Supports bare (`@capability`), positional id (`@capability("my-id")`), or keyword (`@capability(id="my-id")`) forms

Symbol	Signature	Description
`invoke`	`invoke(id: str, args: dict \\| None = None, *, principal: str = "did:local:m0", principal_attrs: dict \\| None = None, store: Store \\| None = None) -> Any`	Synchronous capability dispatch with provenance
`ainvoke`	`async ainvoke(id: str, args: dict \\| None = None, *, principal: str = "did:local:m0", principal_attrs: dict \\| None = None, store: Store \\| None = None) -> Any`	Async wrapper around `invoke` via `asyncio.to_thread`

Symbol	Signature	Description
`@before`	`@before(pattern: str)`	Register middleware to run BEFORE matching capabilities. Receives `(ctx, args)`, may return a dict to update args
`@after`	`@after(pattern: str)`	Register middleware to run AFTER a successful invocation. Receives `(ctx, args, result)`
`@on_error`	`@on_error(pattern: str)`	Register middleware to run when the handler raises. Receives `(ctx, args, exc)`
`@around`	`@around(pattern: str)`	Register middleware that wraps the whole invocation. Receives `(ctx, args, next)`