`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#

Convert class to dict.

Return type:: dict

to_dict() → Dict#

Convert class to dict.

Return type:: dict

asdict_explicit() → Dict#

Convert to dict, keeping only what differs from the class defaults.

See explicit_fields, which this defers to.

Returns:: Fields that differ from the defaults
Return type:: dict

from_dict(dict_obj: Dict) → None#

Gets attributes values from given dictionary

Parameters:

dict_obj (Dict) – Dictionary {attribute_name: attribute_value}

Raises:

ValueError – If attribute_name in dictionary does not exists in class attributes
TypeError – If attribute_value type in dictionary does not correspond to class attribute type

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

Update class attributes from yaml, json, or toml

Parameters:

file_path – Path to config file (.yaml, .json, .toml)
nested_root_name – Nested root name for the config, defaults to None
get_common – Whether to get extra config root (for merging), defaults to False

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

Dump to json

Returns:: description
Return type:: str | bytes | bytearray

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

Gets attributes values from given json

Parameters:: json_obj (str | bytes | bytearray) – Json object

has_attribute(attr_name: str) → bool#

Checks if class object has attribute with given name

Parameters:: attr_name (str) – description
Returns:: If object has attribute with given name
Return type:: bool

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

Gets type of given attribute name

Parameters:: attr_name (str) – description
Raises:: AttributeError – If class does not have attribute with given name
Returns:: Attribute type
Return type:: type

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

Updates the value of an attribute in the class

Parameters:

attr_name (str) – Attribute name - can be nested name
attr_value (Any) – Attribute value

Raises:

AttributeError – If class does not contain attribute with given name
TypeError – If class attribute with given name if of different type

Returns:

If attribute value is updated

Return type:

bool

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

Returns a dictionary with metadata about each field in the class.

This includes the field’s name, type annotation, and parsed validator info.

Returns:: A dictionary where keys are field names and values are dicts of metadata.

class ros_sugar.robot.registries.EventSpec#

Bases: ros_sugar.config.BaseAttrs

Introspection record for one event factory.

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

Convert class to dict.

Return type:: dict

to_dict() → Dict#

Convert class to dict.

Return type:: dict

asdict_explicit() → Dict#

Convert to dict, keeping only what differs from the class defaults.

See explicit_fields, which this defers to.

Returns:: Fields that differ from the defaults
Return type:: dict

from_dict(dict_obj: Dict) → None#

Gets attributes values from given dictionary

Parameters:

dict_obj (Dict) – Dictionary {attribute_name: attribute_value}

Raises:

ValueError – If attribute_name in dictionary does not exists in class attributes
TypeError – If attribute_value type in dictionary does not correspond to class attribute type

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

Update class attributes from yaml, json, or toml

Parameters:

file_path – Path to config file (.yaml, .json, .toml)
nested_root_name – Nested root name for the config, defaults to None
get_common – Whether to get extra config root (for merging), defaults to False

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

Dump to json

Returns:: description
Return type:: str | bytes | bytearray

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

Gets attributes values from given json

Parameters:: json_obj (str | bytes | bytearray) – Json object

has_attribute(attr_name: str) → bool#

Checks if class object has attribute with given name

Parameters:: attr_name (str) – description
Returns:: If object has attribute with given name
Return type:: bool

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

Gets type of given attribute name

Parameters:: attr_name (str) – description
Raises:: AttributeError – If class does not have attribute with given name
Returns:: Attribute type
Return type:: type

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

Updates the value of an attribute in the class

Parameters:

attr_name (str) – Attribute name - can be nested name
attr_value (Any) – Attribute value

Raises:

AttributeError – If class does not contain attribute with given name
TypeError – If class attribute with given name if of different type

Returns:

If attribute value is updated

Return type:

bool

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

Returns a dictionary with metadata about each field in the class.

This includes the field’s name, type annotation, and parsed validator info.

Returns:: A dictionary where keys are field names and values are dicts of metadata.

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]#: Return the registered factory names.

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

Bases: ros_sugar.robot.registries._FactoryRegistry

Registry of factories producing core.event.Event.

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

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

names() → List[str]#: Return the registered factory names.

ros_sugar.robot.registries#

Module Contents#

Classes#

Functions#

API#

`ros_sugar.robot.registries`#