robonix_api.capability¶

User-facing CapabilityProvider classes: Primitive, Service, Skill.

A Robonix package instantiates exactly one of these. The framework talks to atlas (RegisterPrimitive/Service/Skill + DeclareCapability + Heartbeat), serves the lifecycle gRPC API (Driver(CMD_INIT/ACTIVATE/DEACTIVATE/SHUTDOWN)), and provides thin helpers over rclpy / grpcio / FastMCP for the most common patterns.

Internal _ProviderBase shares all the lifecycle / decorator / server plumbing; the three concrete classes differ only in which atlas Register RPC they call.

Layered API:

Layer 1 (always available): declare_capability, connect_capability, spawn subprocess, sentinel waits.
Layer 2 (opt-in convenience): create_publisher / create_subscription for ROS 2; @provider.provides_grpc(…) / @provider.provides_mcp(…) decorators that register the handler AND atlas-declare the Capability in one step (description is pulled from the function’s docstring or passed explicitly).

Classes

`Primitive`(id, namespace, *[, pkg_root, md_path])	A hardware or data-source capability provider.
`Service`(id, namespace, *[, pkg_root, md_path])	A capability provider composed from primitives or other services.
`Skill`(id, namespace, *[, pkg_root, md_path])	A model-backed capability provider activated by Executor on demand.

class robonix_api.capability.Primitive(id: str, namespace: str, *, pkg_root: Path | None = None, md_path: str | None = None)[source]¶

Bases: _ProviderBase

A hardware or data-source capability provider.

Examples include a camera, lidar, or CAN chassis driver.

Example:

primitive_cam = Primitive(
    id="webots_tiago_camera_front",
    namespace="robonix/primitive/camera",
)

class robonix_api.capability.Service(id: str, namespace: str, *, pkg_root: Path | None = None, md_path: str | None = None)[source]¶

Bases: _ProviderBase

A capability provider composed from primitives or other services.

Examples include mapping, navigation, scene, memory, and speech services.

Example:

service_mapping = Service(
    id="mapping",
    namespace="robonix/service/mapping",
)

class robonix_api.capability.Skill(id: str, namespace: str, *, pkg_root: Path | None = None, md_path: str | None = None)[source]¶

Bases: _ProviderBase

A model-backed capability provider activated by Executor on demand.

A skill starts in INACTIVE and becomes ACTIVE when invoked.

Example:

skill_explore = Skill(
    id="explore",
    namespace="robonix/skill/explore",
)