`ros_sugar.robot.registries`#

Action and Event registries for robot plugins.

A plugin exposes high-level, user-triggerable behaviours as factories: calling plugin.actions.stand_up() constructs a fresh core.action.Action, and plugin.events.low_battery(0.15) constructs a fresh core.event.Event. Factories (rather than pre-built instances) let recipe authors pass per-call arguments, plain values or MsgConditionBuilder references from any topic.

Action factories can carry an OpenAI-style tool description (decorate them with plugin_action or stamp _tool_description directly). Downstream LLM-driven components (e.g. in EmbodiedAgents) consume these via ActionRegistry.tool_descriptions.

Module Contents#

Classes#

`ActionSpec`	Introspection record for one action factory.
`EventSpec`	Introspection record for one event factory.
`ActionRegistry`	Registry of factories producing `core.action.Action`.
`EventRegistry`	Registry of factories producing `core.event.Event`.

Functions#

plugin_action

Decorator that stamps an LLM-tool description on a plugin action factory.

API#

ros_sugar.robot.registries.plugin_action(function: Optional[Callable] = None, description: Optional[Union[str, Dict]] = None)#

Decorator that stamps an LLM-tool description on a plugin action factory.

Mirrors utils.component_action for actions exposed through a robot plugin. The decorated callable is unchanged at runtime; it carries a _tool_description attribute that ActionRegistry surfaces.

Usage::

@plugin_action(description="Sit down or stand up from a sitting position")
def _make_sit_stand(self) -> Action:
    ...

@plugin_action(description={
    "name": "move_to",
    "description": "Drive to an absolute pose",
    "parameters": {
        "type": "object",
        "properties": {
            "x": {"type": "number"},
            "y": {"type": "number"},
        },
        "required": ["x", "y"],
    },
})
def _make_move_to(self) -> Action:
    ...

A plain string becomes the function description with a zero-arg parameter schema. A dict is taken as the OpenAI function block; missing fields are filled in by ActionRegistry.tool_descriptions.

class ros_sugar.robot.registries.ActionSpec#

Bases: ros_sugar.config.BaseAttrs

Introspection record for one action factory.

asdict(filter: Optional[Callable] = None) → Dict#

to_dict() → Dict#

from_dict(dict_obj: Dict) → None#

from_file(file_path: str, nested_root_name: Union[str, None] = None, get_common: bool = False) → bool#

to_json() → Union[str, bytes, bytearray]#

from_json(json_obj: Union[str, bytes, bytearray]) → None#

has_attribute(attr_name: str) → bool#

get_attribute_type(attr_name: str) → Optional[type]#

update_value(attr_name: str, attr_value: Any) → bool#

classmethod get_fields_info(class_object) → Dict[str, Dict[str, Any]]#

class ros_sugar.robot.registries.EventSpec#

Bases: ros_sugar.config.BaseAttrs

Introspection record for one event factory.

asdict(filter: Optional[Callable] = None) → Dict#

to_dict() → Dict#

from_dict(dict_obj: Dict) → None#

from_file(file_path: str, nested_root_name: Union[str, None] = None, get_common: bool = False) → bool#

to_json() → Union[str, bytes, bytearray]#

from_json(json_obj: Union[str, bytes, bytearray]) → None#

has_attribute(attr_name: str) → bool#

get_attribute_type(attr_name: str) → Optional[type]#

update_value(attr_name: str, attr_value: Any) → bool#

classmethod get_fields_info(class_object) → Dict[str, Dict[str, Any]]#

class ros_sugar.robot.registries.ActionRegistry(factories: Dict[str, Callable[..., ros_sugar.core.action.Action]])#

Bases: ros_sugar.robot.registries._FactoryRegistry

Registry of factories producing core.action.Action.

Parameters:: factories – Mapping of action name to a zero-or-more-arg callable that returns a fresh Action.

list() → List[ros_sugar.robot.registries.ActionSpec]#: Return introspection specs for every registered action.

tool_descriptions(namespace: Optional[str] = None) → List[Dict[str, Any]]#

Return OpenAI-style tool descriptions for every registered action.

Each entry is a dict ready to drop into an LLM-tool list. The tool name is {namespace}.{action_name} when namespace is given.

Sources, in order of preference:

factory._tool_description stamped via plugin_action (string or OpenAI function dict). Missing schema fields are filled in with a zero-arg default.
The factory’s first docstring line — short description, zero-arg schema.
A bare description string of "<no description>".

tool_descriptions_json(namespace: Optional[str] = None) → str#: JSON-serialized form of tool_descriptions.

names() → List[str]#

class ros_sugar.robot.registries.EventRegistry(factories: Dict[str, Callable[..., ros_sugar.core.event.Event]])#