luckyrobots 0.1.66__py3-none-any.whl → 0.1.72__py3-none-any.whl

luckyrobots/grpc/generated/telemetry_pb2.py

@@ -0,0 +1,47 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: telemetry.proto
+# Protobuf Python Version: 6.31.1
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    6,
+    31,
+    1,
+    '',
+    'telemetry.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x0ftelemetry.proto\x12\thazel.rpc\"Z\n\x0fTelemetrySchema\x12\x19\n\x11observation_names\x18\x01 \x03(\t\x12\x14\n\x0c\x61\x63tion_names\x18\x02 \x03(\t\x12\n\n\x02nq\x18\x03 \x01(\r\x12\n\n\x02nu\x18\x04 \x01(\r\"\x1b\n\x19GetTelemetrySchemaRequest\"H\n\x1aGetTelemetrySchemaResponse\x12*\n\x06schema\x18\x01 \x01(\x0b\x32\x1a.hazel.rpc.TelemetrySchema\",\n\x16StreamTelemetryRequest\x12\x12\n\ntarget_fps\x18\x01 \x01(\r\"\x7f\n\x0eTelemetryFrame\x12\x14\n\x0ctimestamp_ms\x18\x01 \x01(\x04\x12\x14\n\x0c\x66rame_number\x18\x02 \x01(\r\x12\x12\n\ntask_index\x18\x03 \x01(\r\x12\x18\n\x10observation_qpos\x18\x04 \x03(\x02\x12\x13\n\x0b\x61\x63tion_ctrl\x18\x05 \x03(\x02\x32\xc8\x01\n\x10TelemetryService\x12\x61\n\x12GetTelemetrySchema\x12$.hazel.rpc.GetTelemetrySchemaRequest\x1a%.hazel.rpc.GetTelemetrySchemaResponse\x12Q\n\x0fStreamTelemetry\x12!.hazel.rpc.StreamTelemetryRequest\x1a\x19.hazel.rpc.TelemetryFrame0\x01\x42\x03\xf8\x01\x01\x62\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'telemetry_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  _globals['DESCRIPTOR']._loaded_options = None
+  _globals['DESCRIPTOR']._serialized_options = b'\370\001\001'
+  _globals['_TELEMETRYSCHEMA']._serialized_start=30
+  _globals['_TELEMETRYSCHEMA']._serialized_end=120
+  _globals['_GETTELEMETRYSCHEMAREQUEST']._serialized_start=122
+  _globals['_GETTELEMETRYSCHEMAREQUEST']._serialized_end=149
+  _globals['_GETTELEMETRYSCHEMARESPONSE']._serialized_start=151
+  _globals['_GETTELEMETRYSCHEMARESPONSE']._serialized_end=223
+  _globals['_STREAMTELEMETRYREQUEST']._serialized_start=225
+  _globals['_STREAMTELEMETRYREQUEST']._serialized_end=269
+  _globals['_TELEMETRYFRAME']._serialized_start=271
+  _globals['_TELEMETRYFRAME']._serialized_end=398
+  _globals['_TELEMETRYSERVICE']._serialized_start=401
+  _globals['_TELEMETRYSERVICE']._serialized_end=601
+# @@protoc_insertion_point(module_scope)

luckyrobots/grpc/generated/telemetry_pb2_grpc.py

@@ -0,0 +1,143 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+import warnings
+
+from . import telemetry_pb2 as telemetry__pb2
+
+GRPC_GENERATED_VERSION = '1.76.0'
+GRPC_VERSION = grpc.__version__
+_version_not_supported = False
+
+try:
+    from grpc._utilities import first_version_is_lower
+    _version_not_supported = first_version_is_lower(GRPC_VERSION, GRPC_GENERATED_VERSION)
+except ImportError:
+    _version_not_supported = True
+
+if _version_not_supported:
+    raise RuntimeError(
+        f'The grpc package installed is at version {GRPC_VERSION},'
+        + ' but the generated code in telemetry_pb2_grpc.py depends on'
+        + f' grpcio>={GRPC_GENERATED_VERSION}.'
+        + f' Please upgrade your grpc module to grpcio>={GRPC_GENERATED_VERSION}'
+        + f' or downgrade your generated code using grpcio-tools<={GRPC_VERSION}.'
+    )
+
+
+class TelemetryServiceStub(object):
+    """Stream-only service intended for external tools (plotting, training logs, debugging).
+    """
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.GetTelemetrySchema = channel.unary_unary(
+                '/hazel.rpc.TelemetryService/GetTelemetrySchema',
+                request_serializer=telemetry__pb2.GetTelemetrySchemaRequest.SerializeToString,
+                response_deserializer=telemetry__pb2.GetTelemetrySchemaResponse.FromString,
+                _registered_method=True)
+        self.StreamTelemetry = channel.unary_stream(
+                '/hazel.rpc.TelemetryService/StreamTelemetry',
+                request_serializer=telemetry__pb2.StreamTelemetryRequest.SerializeToString,
+                response_deserializer=telemetry__pb2.TelemetryFrame.FromString,
+                _registered_method=True)
+
+
+class TelemetryServiceServicer(object):
+    """Stream-only service intended for external tools (plotting, training logs, debugging).
+    """
+
+    def GetTelemetrySchema(self, request, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def StreamTelemetry(self, request, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+
+def add_TelemetryServiceServicer_to_server(servicer, server):
+    rpc_method_handlers = {
+            'GetTelemetrySchema': grpc.unary_unary_rpc_method_handler(
+                    servicer.GetTelemetrySchema,
+                    request_deserializer=telemetry__pb2.GetTelemetrySchemaRequest.FromString,
+                    response_serializer=telemetry__pb2.GetTelemetrySchemaResponse.SerializeToString,
+            ),
+            'StreamTelemetry': grpc.unary_stream_rpc_method_handler(
+                    servicer.StreamTelemetry,
+                    request_deserializer=telemetry__pb2.StreamTelemetryRequest.FromString,
+                    response_serializer=telemetry__pb2.TelemetryFrame.SerializeToString,
+            ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler(
+            'hazel.rpc.TelemetryService', rpc_method_handlers)
+    server.add_generic_rpc_handlers((generic_handler,))
+    server.add_registered_method_handlers('hazel.rpc.TelemetryService', rpc_method_handlers)
+
+
+ # This class is part of an EXPERIMENTAL API.
+class TelemetryService(object):
+    """Stream-only service intended for external tools (plotting, training logs, debugging).
+    """
+
+    @staticmethod
+    def GetTelemetrySchema(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            '/hazel.rpc.TelemetryService/GetTelemetrySchema',
+            telemetry__pb2.GetTelemetrySchemaRequest.SerializeToString,
+            telemetry__pb2.GetTelemetrySchemaResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)
+
+    @staticmethod
+    def StreamTelemetry(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_stream(
+            request,
+            target,
+            '/hazel.rpc.TelemetryService/StreamTelemetry',
+            telemetry__pb2.StreamTelemetryRequest.SerializeToString,
+            telemetry__pb2.TelemetryFrame.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)

luckyrobots/grpc/generated/viewport_pb2.py

@@ -0,0 +1,50 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: viewport.proto
+# Protobuf Python Version: 6.31.1
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    6,
+    31,
+    1,
+    '',
+    'viewport.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from . import media_pb2 as media__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x0eviewport.proto\x12\thazel.rpc\x1a\x0bmedia.proto\"v\n\x1aStartViewportStreamRequest\x12\x15\n\rviewport_name\x18\x01 \x01(\t\x12\x12\n\ntarget_fps\x18\x02 \x01(\r\x12\r\n\x05width\x18\x03 \x01(\r\x12\x0e\n\x06height\x18\x04 \x01(\r\x12\x0e\n\x06\x66ormat\x18\x05 \x01(\t\"l\n\x14ViewportStreamConfig\x12\x11\n\tstreaming\x18\x01 \x01(\x08\x12\x15\n\rviewport_name\x18\x02 \x01(\t\x12\x0b\n\x03\x66ps\x18\x03 \x01(\r\x12\r\n\x05width\x18\x04 \x01(\r\x12\x0e\n\x06height\x18\x05 \x01(\r\"\x1b\n\x19StopViewportStreamRequest\"-\n\x1aStopViewportStreamResponse\x12\x0f\n\x07success\x18\x01 \x01(\x08\"\x18\n\x16GetViewportInfoRequest\"o\n\x17GetViewportInfoResponse\x12\x1b\n\x13\x61vailable_viewports\x18\x01 \x03(\t\x12\x37\n\x0e\x63urrent_config\x18\x02 \x01(\x0b\x32\x1f.hazel.rpc.ViewportStreamConfig2\xbd\x01\n\x0fViewportService\x12X\n\x0fGetViewportInfo\x12!.hazel.rpc.GetViewportInfoRequest\x1a\".hazel.rpc.GetViewportInfoResponse\x12P\n\x0eStreamViewport\x12%.hazel.rpc.StartViewportStreamRequest\x1a\x15.hazel.rpc.ImageFrame0\x01\x42\x03\xf8\x01\x01\x62\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'viewport_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  _globals['DESCRIPTOR']._loaded_options = None
+  _globals['DESCRIPTOR']._serialized_options = b'\370\001\001'
+  _globals['_STARTVIEWPORTSTREAMREQUEST']._serialized_start=42
+  _globals['_STARTVIEWPORTSTREAMREQUEST']._serialized_end=160
+  _globals['_VIEWPORTSTREAMCONFIG']._serialized_start=162
+  _globals['_VIEWPORTSTREAMCONFIG']._serialized_end=270
+  _globals['_STOPVIEWPORTSTREAMREQUEST']._serialized_start=272
+  _globals['_STOPVIEWPORTSTREAMREQUEST']._serialized_end=299
+  _globals['_STOPVIEWPORTSTREAMRESPONSE']._serialized_start=301
+  _globals['_STOPVIEWPORTSTREAMRESPONSE']._serialized_end=346
+  _globals['_GETVIEWPORTINFOREQUEST']._serialized_start=348
+  _globals['_GETVIEWPORTINFOREQUEST']._serialized_end=372
+  _globals['_GETVIEWPORTINFORESPONSE']._serialized_start=374
+  _globals['_GETVIEWPORTINFORESPONSE']._serialized_end=485
+  _globals['_VIEWPORTSERVICE']._serialized_start=488
+  _globals['_VIEWPORTSERVICE']._serialized_end=677
+# @@protoc_insertion_point(module_scope)

luckyrobots/grpc/generated/viewport_pb2_grpc.py

@@ -0,0 +1,144 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+import warnings
+
+from . import media_pb2 as media__pb2
+from . import viewport_pb2 as viewport__pb2
+
+GRPC_GENERATED_VERSION = '1.76.0'
+GRPC_VERSION = grpc.__version__
+_version_not_supported = False
+
+try:
+    from grpc._utilities import first_version_is_lower
+    _version_not_supported = first_version_is_lower(GRPC_VERSION, GRPC_GENERATED_VERSION)
+except ImportError:
+    _version_not_supported = True
+
+if _version_not_supported:
+    raise RuntimeError(
+        f'The grpc package installed is at version {GRPC_VERSION},'
+        + ' but the generated code in viewport_pb2_grpc.py depends on'
+        + f' grpcio>={GRPC_GENERATED_VERSION}.'
+        + f' Please upgrade your grpc module to grpcio>={GRPC_GENERATED_VERSION}'
+        + f' or downgrade your generated code using grpcio-tools<={GRPC_VERSION}.'
+    )
+
+
+class ViewportServiceStub(object):
+    """Streams pixels from a named viewport (useful for external visualization / training input).
+    """
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.GetViewportInfo = channel.unary_unary(
+                '/hazel.rpc.ViewportService/GetViewportInfo',
+                request_serializer=viewport__pb2.GetViewportInfoRequest.SerializeToString,
+                response_deserializer=viewport__pb2.GetViewportInfoResponse.FromString,
+                _registered_method=True)
+        self.StreamViewport = channel.unary_stream(
+                '/hazel.rpc.ViewportService/StreamViewport',
+                request_serializer=viewport__pb2.StartViewportStreamRequest.SerializeToString,
+                response_deserializer=media__pb2.ImageFrame.FromString,
+                _registered_method=True)
+
+
+class ViewportServiceServicer(object):
+    """Streams pixels from a named viewport (useful for external visualization / training input).
+    """
+
+    def GetViewportInfo(self, request, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def StreamViewport(self, request, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+
+def add_ViewportServiceServicer_to_server(servicer, server):
+    rpc_method_handlers = {
+            'GetViewportInfo': grpc.unary_unary_rpc_method_handler(
+                    servicer.GetViewportInfo,
+                    request_deserializer=viewport__pb2.GetViewportInfoRequest.FromString,
+                    response_serializer=viewport__pb2.GetViewportInfoResponse.SerializeToString,
+            ),
+            'StreamViewport': grpc.unary_stream_rpc_method_handler(
+                    servicer.StreamViewport,
+                    request_deserializer=viewport__pb2.StartViewportStreamRequest.FromString,
+                    response_serializer=media__pb2.ImageFrame.SerializeToString,
+            ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler(
+            'hazel.rpc.ViewportService', rpc_method_handlers)
+    server.add_generic_rpc_handlers((generic_handler,))
+    server.add_registered_method_handlers('hazel.rpc.ViewportService', rpc_method_handlers)
+
+
+ # This class is part of an EXPERIMENTAL API.
+class ViewportService(object):
+    """Streams pixels from a named viewport (useful for external visualization / training input).
+    """
+
+    @staticmethod
+    def GetViewportInfo(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            '/hazel.rpc.ViewportService/GetViewportInfo',
+            viewport__pb2.GetViewportInfoRequest.SerializeToString,
+            viewport__pb2.GetViewportInfoResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)
+
+    @staticmethod
+    def StreamViewport(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_stream(
+            request,
+            target,
+            '/hazel.rpc.ViewportService/StreamViewport',
+            viewport__pb2.StartViewportStreamRequest.SerializeToString,
+            media__pb2.ImageFrame.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)

luckyrobots/grpc/proto/agent.proto

@@ -0,0 +1,213 @@
+syntax = "proto3";
+
+// Agent + observation service definitions for the LuckyEngine / Hazel ScriptCore gRPC API (v1).
+
+package hazel.rpc;
+
+option cc_enable_arenas = true;
+
+import "common.proto";
+import "media.proto";
+import "mujoco.proto";
+import "telemetry.proto";
+
+// Schema for an RL-style agent. `*_names` are informative; sizes are authoritative.
+message AgentSchema {
+    string agent_name = 1;
+    repeated string observation_names = 2;
+    repeated string action_names = 3;
+    uint32 observation_size = 4;
+    uint32 action_size = 5;
+}
+
+message GetAgentSchemaRequest {
+    // Agent logical name. Convention in this repo is `agent_0`, `agent_1`, ...
+    // Empty typically means "default agent".
+    string agent_name = 1;
+}
+
+message GetAgentSchemaResponse {
+    AgentSchema schema = 1;
+}
+
+message StreamAgentRequest {
+    // Agent logical name. If empty, server may fall back to a default agent.
+    string agent_name = 1;
+    // Client hint: desired update rate. Server may clamp.
+    uint32 target_fps = 2;
+}
+
+// Domain randomization configuration for physics parameters.
+// All range fields are [min, max] pairs. Empty ranges mean "use defaults".
+message DomainRandomizationConfig {
+    // Initial state randomization
+    repeated float pose_position_noise = 1;   // [x, y, z] position noise std
+    float pose_orientation_noise = 2;         // Orientation noise std (radians)
+    float joint_position_noise = 3;           // Joint position noise std
+    float joint_velocity_noise = 4;           // Joint velocity noise std
+
+    // Physics parameters (all [min, max] ranges)
+    repeated float friction_range = 5;        // Surface friction coefficient
+    repeated float restitution_range = 6;     // Bounce/restitution coefficient
+    repeated float mass_scale_range = 7;      // Body mass multiplier
+    repeated float com_offset_range = 8;      // Center of mass offset
+
+    // Motor/actuator randomization
+    repeated float motor_strength_range = 9;  // Motor strength multiplier
+    repeated float motor_offset_range = 10;   // Motor position offset
+
+    // External disturbances
+    repeated float push_interval_range = 11;  // Time between pushes [min, max]
+    repeated float push_velocity_range = 12;  // Push velocity magnitude [min, max]
+
+    // Terrain configuration
+    string terrain_type = 13;                 // Terrain type identifier
+    float terrain_difficulty = 14;            // Terrain difficulty level
+}
+
+message ResetAgentRequest {
+    // Agent logical name. Convention in this repo is `agent_0`, `agent_1`, ...
+    // Empty typically means "default agent" (agent_0).
+    string agent_name = 1;
+
+    // Optional domain randomization config for this reset.
+    // If not provided, use defaults or keep previous values.
+    DomainRandomizationConfig dr_config = 2;
+}
+
+message ResetAgentResponse {
+    bool success = 1;
+    string message = 2;
+}
+
+// Agent observation stream frame.
+// This stream is server->client; external actions are currently sent via MujocoService.SendControl.
+message AgentFrame {
+    // Wall-clock timestamp in milliseconds (set by server on outgoing frames)
+    uint64 timestamp_ms = 1;
+    // Monotonic frame counter (set by server on outgoing frames)
+    uint32 frame_number = 2;
+
+    // Flat observation vector for this frame, as defined by the Agent's ObservationSpec.
+    repeated float observations = 3;
+
+    // Flat action vector for this frame.
+    // For frames sent from the client to the server, this carries the actions that
+    // should be applied for the next simulation step.
+    // For frames sent from the server to the client, this typically mirrors the last
+    // applied actions for debugging/telemetry.
+    repeated float actions = 4;
+
+    // Optional agent identifier, used when multiplexing multiple agents over a single
+    // stream. If empty, the server may fall back to a default agent.
+    string agent_name = 5;
+
+    // Optional target FPS hint requested by the client. The server may clamp or ignore
+    // this value depending on simulation timing constraints.
+    uint32 target_fps = 6;
+}
+
+// =============================================================================
+// Observation RPC (single-shot snapshot)
+// =============================================================================
+
+// Single-shot camera snapshot request (mirrors StreamCameraRequest without fps).
+message GetCameraFrameRequest {
+    oneof identifier {
+        EntityId id = 1;
+        string name = 2;
+    }
+
+    uint32 width = 3;            // Desired width (0 = native)
+    uint32 height = 4;           // Desired height (0 = native)
+    string format = 5;           // "raw", "jpeg" (default: raw)
+}
+
+// Single-shot viewport snapshot request (mirrors StartViewportStreamRequest without fps).
+message GetViewportFrameRequest {
+    string viewport_name = 1;
+    uint32 width = 2;            // Desired width (0 = native)
+    uint32 height = 3;           // Desired height (0 = native)
+    string format = 4;           // "raw", "jpeg" (default: raw)
+}
+
+// Request a unified observation snapshot. The server decides the exact meaning of
+// "observation" based on the active scene/agent configuration and the fields selected here.
+message GetObservationRequest {
+    // Target robot (used for MujocoService-style state and external actions).
+    string robot_name = 1;
+
+    // Target agent (used for RL-style flattened observation vectors). Empty means default agent.
+    string agent_name = 2;
+
+    // Include components in the response (server may ignore unsupported fields).
+    bool include_joint_state = 3;
+    bool include_agent_frame = 4;
+    bool include_telemetry = 5;
+
+    // Optional image snapshots.
+    repeated GetCameraFrameRequest cameras = 6;
+    repeated GetViewportFrameRequest viewports = 7;
+}
+
+message GetObservationResponse {
+    bool success = 1;
+    string message = 2;
+
+    // Timestamp/frame_number are best-effort; server may use whichever timing source is available.
+    uint64 timestamp_ms = 3;
+    uint32 frame_number = 4;
+
+    // Optional components.
+    JointState joint_state = 5;
+    AgentFrame agent_frame = 6;
+    TelemetryFrame telemetry = 7;
+
+    repeated NamedImageFrame camera_frames = 8;
+    repeated NamedImageFrame viewport_frames = 9;
+}
+
+// =============================================================================
+// Step RPC (synchronous RL step)
+// =============================================================================
+
+// Request to step the simulation with the provided action.
+// This is the recommended interface for RL training - it combines
+// SendControl + physics step + GetObservation into a single RPC.
+message StepRequest {
+    // Agent logical name. Empty means default agent.
+    string agent_name = 1;
+    // Action vector to apply for this step.
+    repeated float actions = 2;
+    // Optional timeout in milliseconds. 0 means use server default.
+    uint32 timeout_ms = 3;
+}
+
+message StepResponse {
+    bool success = 1;
+    string message = 2;
+    // Observation after the physics step completed.
+    AgentFrame observation = 3;
+    // Time taken for the physics step in microseconds (for profiling).
+    uint64 physics_step_duration_us = 4;
+}
+
+// Per-agent RL-style observation streaming (training / inference clients consume this).
+service AgentService {
+    rpc GetAgentSchema(GetAgentSchemaRequest) returns (GetAgentSchemaResponse);
+    // Single-shot observation snapshot (unified observation surface).
+    rpc GetObservation(GetObservationRequest) returns (GetObservationResponse);
+    // Server-streaming observations (and optional action echo) for a single agent.
+    //
+    // The client specifies which agent to stream via StreamAgentRequest and may
+    // provide a target FPS hint. Actions are currently sent via MujocoService
+    // (SendControl); AgentFrame.actions is primarily used for telemetry.
+    rpc StreamAgent(StreamAgentRequest) returns (stream AgentFrame);
+    // Reset a specific agent (full reset: clear buffers, reset state, resample commands, apply MuJoCo state).
+    // Useful for multi-env RL where individual agents need to be reset without resetting the entire scene.
+    rpc ResetAgent(ResetAgentRequest) returns (ResetAgentResponse);
+    // Synchronous RL step: apply action, wait for physics, return observation.
+    // This is the recommended interface for RL training as it eliminates
+    // one network round-trip compared to separate SendControl + GetObservation.
+    rpc Step(StepRequest) returns (StepResponse);
+}

luckyrobots/grpc/proto/camera.proto

@@ -0,0 +1,41 @@
+syntax = "proto3";
+
+// Camera service definitions for the LuckyEngine / Hazel ScriptCore gRPC API (v1).
+
+package hazel.rpc;
+
+option cc_enable_arenas = true;
+
+import "common.proto";
+import "media.proto";
+
+// Camera list entry. `id` matches an entity ID in the scene.
+message CameraInfo {
+    EntityId id = 1;
+    string name = 2;
+}
+
+message ListCamerasRequest {}
+
+message ListCamerasResponse {
+    repeated CameraInfo cameras = 1;
+}
+
+// Start a camera stream by `id` or `name`.
+message StreamCameraRequest {
+    oneof identifier {
+        EntityId id = 1;
+        string name = 2;
+    }
+
+    uint32 target_fps = 3;       // Desired frames per second
+    uint32 width = 4;            // Desired width (0 = native)
+    uint32 height = 5;           // Desired height (0 = native)
+    string format = 6;           // "raw", "jpeg" (default: raw)
+}
+
+// Streams pixels from a camera entity (useful for external perception / debugging).
+service CameraService {
+    rpc ListCameras(ListCamerasRequest) returns (ListCamerasResponse);
+    rpc StreamCamera(StreamCameraRequest) returns (stream ImageFrame);
+}

luckyrobots/grpc/proto/common.proto

@@ -0,0 +1,36 @@
+syntax = "proto3";
+
+// Common/shared types for the LuckyEngine / Hazel ScriptCore gRPC API (v1).
+//
+// Compatibility note:
+// - Avoid renumbering existing field tags (the `= N` numbers). Add new fields with new tags instead.
+
+package hazel.rpc;
+
+option cc_enable_arenas = true;
+
+// Stable entity identifier (maps to engine UUID / entity ID depending on context).
+message EntityId {
+    uint64 id = 1;
+}
+
+// Basic math types for scene transforms.
+message Vec3 {
+    float x = 1;
+    float y = 2;
+    float z = 3;
+}
+
+message Quat {
+    float x = 1;
+    float y = 2;
+    float z = 3;
+    float w = 4;
+}
+
+// World-space transform. Interpretation matches the engine's transform component.
+message Transform {
+    Vec3 position = 1;
+    Quat rotation = 2;
+    Vec3 scale = 3;
+}