robonix-api 0.1.0rc1

Robonix Python client library: write Primitive/Service/Skill packages, talk to atlas, serve Driver lifecycle gRPC, wrap rclpy/FastMCP/grpcio middleware.

robonix-api

Python client library for writing Robonix capability providers — primitives, services, and skills — and talking to the Atlas registry.

Robonix is an embodied-AI operating system. robonix-api is the client-side helper: it gives you Primitive / Service / Skill classes that handle Atlas registration, the Driver lifecycle gRPC server, and thin wrappers over rclpy / FastMCP / grpcio. The Atlas server itself is a separate Rust binary (robonix-atlas, see the main repo).

Install

pip install robonix-api

Optional extras:

pip install "robonix-api[codegen]"   # adds grpcio-tools, only needed if you run `rbnx codegen` from Python

ROS 2 (rclpy, sensor_msgs, geometry_msgs, etc.) is not a pip dependency — install ROS 2 Humble via apt on the host. robonix-api's ROS helpers import rclpy lazily, so the rest of the library works even without a ROS install.

Hello, primitive

from robonix_api import Primitive, Ok, Deferred

primitive = Primitive(
    id="my_lidar",
    namespace="robonix/primitive/lidar",
)

@primitive.on_init
def init(cfg: dict):
    topic = cfg.get("lidar_topic", "/scan")
    if not primitive.wait_for_topic(topic, "LaserScan", 30.0):
        return Deferred(f"no LaserScan on {topic} yet")
    primitive.create_publisher(
        contract_id="robonix/primitive/lidar/lidar2d",
        topic=topic,
        msg_type="LaserScan",
    )
    return Ok()

if __name__ == "__main__":
    primitive.run()

That's a complete Robonix primitive — registers with Atlas, serves the Driver lifecycle, waits for the upstream topic, declares a ROS 2 capability for downstream consumers, and blocks on SIGTERM.

What's in the box

• ATLAS — module-level singleton client (ATLAS.register, ATLAS.find_primitive, ATLAS.connect, ...)
• Primitive / Service / Skill — provider base classes with on_init / on_activate / on_deactivate / on_shutdown decorators
• @provider.provides_grpc(contract) / @provider.provides_mcp(contract) — Layer-2 sugar for typed handlers
• Ok / Err / Deferred — lifecycle return values
• mcp_contract — standalone FastMCP decorator (use when you manage your own FastMCP app, e.g. in scene_service)

The Atlas wire protocol (atlas_pb2 / atlas_pb2_grpc) is pre-generated and bundled in the wheel. Per-contract stubs (robonix_contracts_pb2, MCP typed dataclasses) are generated per deployment by rbnx codegen against your contract TOMLs — robonix-api automatically picks them up from <pkg>/rbnx-build/codegen/ at runtime.

Versioning

robonix-api tracks the Robonix v0.1.x series. Wire format and public API are frozen within v0.1.x. Pre-release builds (0.1.0rc*) are published to Test PyPI first; stable releases to PyPI.

The Atlas server (Rust crate robonix-atlas) must be on a compatible minor version. Mixing robonix-api 0.1.x with an Atlas server on a different minor version is unsupported.

Links

• Robonix monorepo — Atlas server, rbnx CLI, examples, full developer guide
• Issues

License

Mulan PSL v2.