brain_deer.commands.registry¶

Command registry: the single source of truth for BrainDeer actions.

A Command is a named, schema-described, callable operation on the viewer. The same registry powers both the human command palette (Cmd/Ctrl+K) and the BrainDeer AI tool-calling loop, so anything a user can type, the assistant can invoke, and vice-versa.

Design goals¶

Flat snake_case ids (e.g. set_colormap, camera_rotate) so ids are valid LLM tool names without sanitisation, and stay backwards compatible with the AI plugin’s original action names.
Typed params with light coercion + validation, and a JSON-schema view for provider-native function calling (OpenAI tools / Anthropic tool_use).
Safety metadata: read_only (safe to auto-run, no state change) and destructive (needs explicit confirmation) drive the approval policy.

Exceptions¶

CommandError

Raised when a command cannot be dispatched (bad args, unknown id, handler error).

Classes¶

`CommandParam`	One typed parameter of a command.
`Command`	A named, schema-described operation on the viewer/session.
`CommandResult`	Structured outcome of a command dispatch.
`CommandRegistry`	Holds commands and dispatches them by id.

Module Contents¶

exception brain_deer.commands.registry.CommandError¶

Bases: Exception

Raised when a command cannot be dispatched (bad args, unknown id, handler error).

class brain_deer.commands.registry.CommandParam¶

One typed parameter of a command.

coerce(value: Any) → Any¶: Coerce a raw (often string/JSON) value to the declared type, with validation.

class brain_deer.commands.registry.Command¶

A named, schema-described operation on the viewer/session.

kwargs_shape() → str¶: Compact human/LLM-readable shape, e.g. {"x": int, "y": int}.

class brain_deer.commands.registry.CommandResult¶: Structured outcome of a command dispatch.

class brain_deer.commands.registry.CommandRegistry¶

Holds commands and dispatches them by id.

add_observer(callback: collections.abc.Callable[[Command, dict[str, Any], CommandResult], None]) → None¶: Register a post-dispatch observer: callback(command, clean_kwargs, result).

add(command_id: str, title: str, category: str, handler: collections.abc.Callable[Ellipsis, Any], *, params: list[CommandParam] | None = None, description: str = '', read_only: bool = False, destructive: bool = False, keywords: list[str] | None = None) → Command¶: Convenience factory + register in one call.

search(query: str) → list[Command]¶: Simple ranked substring search over id/title/keywords for the palette.