robonix_api.lifecycle

Driver lifecycle gRPC server + per-contract Servicer resolution.

Every Robonix provider declares a */driver capability that rbnx boot calls Driver(CMD_INIT, config_json) on. The wire shape is fixed by lib/lifecycle/srv/Driver.srv (uint8 command + string config_json → bool ok + string state + string error).

Per-namespace generated Servicer classes live in robonix_contracts_pb2_grpc: - primitive/<area>/driver → Primitive<Area>DriverServicer - service/<area>/driver → Service<Area>DriverServicer - skill/<area>/driver → Skill<Area>DriverServicer

Users can also declare arbitrary rpc-mode contracts (e.g. primitive/chassis/move) which generate PrimitiveChassisMoveServicer with method Move. We resolve both via the same contract_id_to_pascal() mapping.

Functions

bind_user_handler(servicer_cls, method_name, fn)	Build a dynamic subclass overriding method_name to call fn.
build_lifecycle_servicer(namespace, ...[, ...])	Build (without starting a server) the lifecycle Servicer instance.
coerce_response(response_cls, ret)	Allow handlers to return the response_cls directly OR a dict like {ok, state, error}.
contract_id_to_pascal(contract_id)	Mirror of robonix_codegen::contract_id_to_service_name.
driver_pascal_for_namespace(namespace)	primitive/lidar → PrimitiveLidarDriver (the driver Pascal name).
parse_cfg(request)
resolve_servicer(contract_id, ...)	Find the generated Servicer class + add-to-server fn + canonical method name for a contract.

robonix_api.lifecycle.bind_user_handler(servicer_cls: type, method_name: str, fn: Callable) → type

Build a dynamic subclass overriding method_name to call fn. Adapts to handler arity: 1-arg signatures get (request), 2-arg get (request, context).

robonix_api.lifecycle.build_lifecycle_servicer(namespace: str, contracts_grpc_module, response_cls, *, on_init=None, on_activate=None, on_deactivate=None, on_shutdown=None, on_state_change=None, log_tag: str = 'robonix_api')

Build (without starting a server) the lifecycle Servicer instance.

Returns (instance, add_to_server_fn, pascal_base, method_name=’Driver’) when codegen emitted a <namespace>/driver Servicer for this package, or None when the package doesn’t have a driver contract (typical for system/* services like memory/scene/speech that have no hardware-init phase — they expose only MCP tools / gRPC RPCs and don’t participate in the rbnx-boot Driver(CMD_INIT) handshake).

on_state_change(state, detail) is invoked AFTER each handler returns ok=true and is the framework’s hook for pushing state transitions to atlas. State strings: “inactive” / “active” / “error”. Capability layer wires this; lower-level callers can leave it None.

robonix_api.lifecycle.coerce_response(response_cls, ret) → Any

Allow handlers to return the response_cls directly OR a dict like {ok, state, error}. Capability’s ready/error/deferred helpers return dicts.

robonix_api.lifecycle.contract_id_to_pascal(contract_id: str) → str

Mirror of robonix_codegen::contract_id_to_service_name. Uniform PascalCase, no prefix stripping. robonix/primitive/chassis/twist_in → RobonixPrimitiveChassisTwistIn. mycomp/a/b/c → MycompABC.

robonix_api.lifecycle.driver_pascal_for_namespace(namespace: str) → str

primitive/lidar → PrimitiveLidarDriver (the driver Pascal name).

robonix_api.lifecycle.parse_cfg(request) → dict

robonix_api.lifecycle.resolve_servicer(contract_id: str, contracts_grpc_module)

Find the generated Servicer class + add-to-server fn + canonical method name for a contract. Returns (servicer_class, method_name, add_fn, pascal_base) or None.