luckyrobots 0.1.70__tar.gz → 0.1.72__tar.gz

{luckyrobots-0.1.70 → luckyrobots-0.1.72}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: luckyrobots
-Version: 0.1.70
+Version: 0.1.72
 Summary: Robotics-AI Training in Hyperrealistic Game Environments
 Project-URL: Homepage, https://github.com/luckyrobots/luckyrobots
 Project-URL: Documentation, https://luckyrobots.readthedocs.io

{luckyrobots-0.1.70 → luckyrobots-0.1.72}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "luckyrobots"
-version = "0.1.70"
+version = "0.1.72"
 description = "Robotics-AI Training in Hyperrealistic Game Environments"
 readme = "README.md"
 requires-python = ">=3.10"

{luckyrobots-0.1.70 → luckyrobots-0.1.72}/src/luckyrobots/__init__.py

@@ -7,7 +7,13 @@ simulation environment via gRPC.
 
 from .luckyrobots import LuckyRobots
 from .client import LuckyEngineClient, GrpcConnectionError, BenchmarkResult
-from .models import ObservationResponse, StateSnapshot, CameraData, CameraShape
+from .models import (
+    ObservationResponse,
+    StateSnapshot,
+    CameraData,
+    CameraShape,
+    DomainRandomizationConfig,
+)
 from .utils import FPS
 from .engine import check_updates
 
@@ -24,6 +30,7 @@ __all__ = [
     "StateSnapshot",
     "CameraData",
     "CameraShape",
+    "DomainRandomizationConfig",
     # Utilities
     "FPS",
     "check_updates",

{luckyrobots-0.1.70 → luckyrobots-0.1.72}/src/luckyrobots/client.py

@@ -38,7 +38,7 @@ except Exception as e:  # pragma: no cover
     ) from e
 
 # Import Pydantic models for type-checked responses
-from .models import ObservationResponse, StateSnapshot
+from .models import ObservationResponse, StateSnapshot, DomainRandomizationConfig
 
 
 class GrpcConnectionError(Exception):
@@ -150,7 +150,7 @@ class LuckyEngineClient:
         self._viewport = viewport_pb2_grpc.ViewportServiceStub(self._channel)
         self._camera = camera_pb2_grpc.CameraServiceStub(self._channel)
 
-        logger.info(f"Connected to LuckyEngine gRPC server at {target}")
+        logger.info(f"Channel opened to {target} (server not verified yet)")
 
     def close(self) -> None:
         """Close the gRPC channel."""
@@ -221,6 +221,7 @@ class LuckyEngineClient:
                     pass
 
             if self.health_check(timeout=10.0):
+                logger.info(f"Connected to LuckyEngine gRPC server at {self.host}:{self.port}")
                 return True
 
             time.sleep(poll_interval)
@@ -595,7 +596,12 @@ class LuckyEngineClient:
             ),
         )
 
-    def reset_agent(self, agent_name: str = "", timeout: Optional[float] = None):
+    def reset_agent(
+        self,
+        agent_name: str = "",
+        randomization_cfg: Optional[Any] = None,
+        timeout: Optional[float] = None,
+    ):
         """
         Reset a specific agent (full reset: clear buffers, reset state, resample commands, apply MuJoCo state).
 
@@ -604,17 +610,208 @@ class LuckyEngineClient:
         Args:
             agent_name: Agent logical name. Convention is `agent_0`, `agent_1`, ...
                 Empty string means "default agent" (agent_0).
+            randomization_cfg: Optional domain randomization config for this reset.
             timeout: Timeout in seconds (uses default if None).
 
         Returns:
             ResetAgentResponse with success and message fields.
         """
         timeout = timeout or self.timeout
+
+        # Build request with optional randomization config
+        request_kwargs = {"agent_name": agent_name}
+
+        if randomization_cfg is not None:
+            randomization_proto = self._randomization_to_proto(randomization_cfg)
+            request_kwargs["dr_config"] = randomization_proto
+
         return self.agent.ResetAgent(
-            self.pb.agent.ResetAgentRequest(agent_name=agent_name),
+            self.pb.agent.ResetAgentRequest(**request_kwargs),
             timeout=timeout,
         )
 
+    def step(
+        self,
+        actions: list[float],
+        agent_name: str = "",
+        timeout_ms: int = 0,
+        timeout: Optional[float] = None,
+    ) -> ObservationResponse:
+        """
+        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.
+
+        Args:
+            actions: Action vector to apply for this step.
+            agent_name: Agent name (empty = default agent).
+            timeout_ms: Server-side timeout for the step in milliseconds (0 = use default).
+            timeout: RPC timeout in seconds.
+
+        Returns:
+            ObservationResponse with observation after physics step.
+        """
+        timeout = timeout or self.timeout
+
+        resp = self.agent.Step(
+            self.pb.agent.StepRequest(
+                agent_name=agent_name,
+                actions=actions,
+                timeout_ms=timeout_ms,
+            ),
+            timeout=timeout,
+        )
+
+        if not resp.success:
+            raise RuntimeError(f"Step failed: {resp.message}")
+
+        # Extract observation from AgentFrame
+        agent_frame = resp.observation
+        observations = list(agent_frame.observations) if agent_frame.observations else []
+        actions_out = list(agent_frame.actions) if agent_frame.actions else []
+        timestamp_ms = getattr(agent_frame, "timestamp_ms", 0)
+        frame_number = getattr(agent_frame, "frame_number", 0)
+
+        # Look up cached schema for named access
+        cache_key = agent_name or "agent_0"
+        obs_names, action_names = self._schema_cache.get(cache_key, (None, None))
+
+        return ObservationResponse(
+            observation=observations,
+            actions=actions_out,
+            timestamp_ms=timestamp_ms,
+            frame_number=frame_number,
+            agent_name=cache_key,
+            observation_names=obs_names,
+            action_names=action_names,
+        )
+
+    def set_simulation_mode(
+        self,
+        mode: str = "fast",
+        timeout: Optional[float] = None,
+    ):
+        """
+        Set simulation timing mode.
+
+        Args:
+            mode: "realtime", "deterministic", or "fast"
+                - realtime: Physics runs at 1x wall-clock speed (for visualization)
+                - deterministic: Physics runs at fixed rate (for reproducibility)
+                - fast: Physics runs as fast as possible (for RL training)
+            timeout: RPC timeout in seconds.
+
+        Returns:
+            SetSimulationModeResponse with success and current mode.
+        """
+        timeout = timeout or self.timeout
+
+        mode_map = {
+            "realtime": 0,
+            "deterministic": 1,
+            "fast": 2,
+        }
+        mode_value = mode_map.get(mode.lower(), 2)  # Default to fast
+
+        return self.scene.SetSimulationMode(
+            self.pb.scene.SetSimulationModeRequest(mode=mode_value),
+            timeout=timeout,
+        )
+
+    def get_simulation_mode(self, timeout: Optional[float] = None):
+        """
+        Get current simulation timing mode.
+
+        Returns:
+            GetSimulationModeResponse with mode field (0=realtime, 1=deterministic, 2=fast).
+        """
+        timeout = timeout or self.timeout
+
+        return self.scene.GetSimulationMode(
+            self.pb.scene.GetSimulationModeRequest(),
+            timeout=timeout,
+        )
+
+    def _randomization_to_proto(self, randomization_cfg: Any):
+        """Convert domain randomization config to proto message.
+
+        Accepts any object with randomization config fields (DomainRandomizationConfig,
+        PhysicsDRCfg from luckylab, or similar).
+        """
+        proto_kwargs = {}
+
+        # Helper to get attribute value, checking for None
+        def get_val(name: str, default=None):
+            val = getattr(randomization_cfg, name, default)
+            # Handle both None and empty tuples/lists
+            if val is None or (isinstance(val, (tuple, list)) and len(val) == 0):
+                return None
+            return val
+
+        # Initial state randomization
+        pose_pos = get_val("pose_position_noise")
+        if pose_pos is not None:
+            proto_kwargs["pose_position_noise"] = list(pose_pos)
+
+        pose_ori = get_val("pose_orientation_noise")
+        if pose_ori is not None and pose_ori != 0.0:
+            proto_kwargs["pose_orientation_noise"] = pose_ori
+
+        joint_pos = get_val("joint_position_noise")
+        if joint_pos is not None and joint_pos != 0.0:
+            proto_kwargs["joint_position_noise"] = joint_pos
+
+        joint_vel = get_val("joint_velocity_noise")
+        if joint_vel is not None and joint_vel != 0.0:
+            proto_kwargs["joint_velocity_noise"] = joint_vel
+
+        # Physics parameters (ranges)
+        friction = get_val("friction_range")
+        if friction is not None:
+            proto_kwargs["friction_range"] = list(friction)
+
+        restitution = get_val("restitution_range")
+        if restitution is not None:
+            proto_kwargs["restitution_range"] = list(restitution)
+
+        mass_scale = get_val("mass_scale_range")
+        if mass_scale is not None:
+            proto_kwargs["mass_scale_range"] = list(mass_scale)
+
+        com_offset = get_val("com_offset_range")
+        if com_offset is not None:
+            proto_kwargs["com_offset_range"] = list(com_offset)
+
+        # Motor/actuator
+        motor_strength = get_val("motor_strength_range")
+        if motor_strength is not None:
+            proto_kwargs["motor_strength_range"] = list(motor_strength)
+
+        motor_offset = get_val("motor_offset_range")
+        if motor_offset is not None:
+            proto_kwargs["motor_offset_range"] = list(motor_offset)
+
+        # External disturbances
+        push_interval = get_val("push_interval_range")
+        if push_interval is not None:
+            proto_kwargs["push_interval_range"] = list(push_interval)
+
+        push_velocity = get_val("push_velocity_range")
+        if push_velocity is not None:
+            proto_kwargs["push_velocity_range"] = list(push_velocity)
+
+        # Terrain
+        terrain_type = get_val("terrain_type")
+        if terrain_type is not None and terrain_type != "":
+            proto_kwargs["terrain_type"] = terrain_type
+
+        terrain_diff = get_val("terrain_difficulty")
+        if terrain_diff is not None and terrain_diff != 0.0:
+            proto_kwargs["terrain_difficulty"] = terrain_diff
+
+        return self.pb.agent.DomainRandomizationConfig(**proto_kwargs)
+
     def stream_telemetry(self, target_fps: int = 30):
         """
         Start streaming telemetry data. [PLACEHOLDER - not confirmed working]

luckyrobots-0.1.72/src/luckyrobots/grpc/generated/agent_pb2.py

@@ -0,0 +1,69 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: agent.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,
+    '',
+    'agent.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from . import common_pb2 as common__pb2
+from . import media_pb2 as media__pb2
+from . import mujoco_pb2 as mujoco__pb2
+from . import telemetry_pb2 as telemetry__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x0b\x61gent.proto\x12\thazel.rpc\x1a\x0c\x63ommon.proto\x1a\x0bmedia.proto\x1a\x0cmujoco.proto\x1a\x0ftelemetry.proto\"\x81\x01\n\x0b\x41gentSchema\x12\x12\n\nagent_name\x18\x01 \x01(\t\x12\x19\n\x11observation_names\x18\x02 \x03(\t\x12\x14\n\x0c\x61\x63tion_names\x18\x03 \x03(\t\x12\x18\n\x10observation_size\x18\x04 \x01(\r\x12\x13\n\x0b\x61\x63tion_size\x18\x05 \x01(\r\"+\n\x15GetAgentSchemaRequest\x12\x12\n\nagent_name\x18\x01 \x01(\t\"@\n\x16GetAgentSchemaResponse\x12&\n\x06schema\x18\x01 \x01(\x0b\x32\x16.hazel.rpc.AgentSchema\"<\n\x12StreamAgentRequest\x12\x12\n\nagent_name\x18\x01 \x01(\t\x12\x12\n\ntarget_fps\x18\x02 \x01(\r\"\xa1\x03\n\x19\x44omainRandomizationConfig\x12\x1b\n\x13pose_position_noise\x18\x01 \x03(\x02\x12\x1e\n\x16pose_orientation_noise\x18\x02 \x01(\x02\x12\x1c\n\x14joint_position_noise\x18\x03 \x01(\x02\x12\x1c\n\x14joint_velocity_noise\x18\x04 \x01(\x02\x12\x16\n\x0e\x66riction_range\x18\x05 \x03(\x02\x12\x19\n\x11restitution_range\x18\x06 \x03(\x02\x12\x18\n\x10mass_scale_range\x18\x07 \x03(\x02\x12\x18\n\x10\x63om_offset_range\x18\x08 \x03(\x02\x12\x1c\n\x14motor_strength_range\x18\t \x03(\x02\x12\x1a\n\x12motor_offset_range\x18\n \x03(\x02\x12\x1b\n\x13push_interval_range\x18\x0b \x03(\x02\x12\x1b\n\x13push_velocity_range\x18\x0c \x03(\x02\x12\x14\n\x0cterrain_type\x18\r \x01(\t\x12\x1a\n\x12terrain_difficulty\x18\x0e \x01(\x02\"`\n\x11ResetAgentRequest\x12\x12\n\nagent_name\x18\x01 \x01(\t\x12\x37\n\tdr_config\x18\x02 \x01(\x0b\x32$.hazel.rpc.DomainRandomizationConfig\"6\n\x12ResetAgentResponse\x12\x0f\n\x07success\x18\x01 \x01(\x08\x12\x0f\n\x07message\x18\x02 \x01(\t\"\x87\x01\n\nAgentFrame\x12\x14\n\x0ctimestamp_ms\x18\x01 \x01(\x04\x12\x14\n\x0c\x66rame_number\x18\x02 \x01(\r\x12\x14\n\x0cobservations\x18\x03 \x03(\x02\x12\x0f\n\x07\x61\x63tions\x18\x04 \x03(\x02\x12\x12\n\nagent_name\x18\x05 \x01(\t\x12\x12\n\ntarget_fps\x18\x06 \x01(\r\"\x87\x01\n\x15GetCameraFrameRequest\x12!\n\x02id\x18\x01 \x01(\x0b\x32\x13.hazel.rpc.EntityIdH\x00\x12\x0e\n\x04name\x18\x02 \x01(\tH\x00\x12\r\n\x05width\x18\x03 \x01(\r\x12\x0e\n\x06height\x18\x04 \x01(\r\x12\x0e\n\x06\x66ormat\x18\x05 \x01(\tB\x0c\n\nidentifier\"_\n\x17GetViewportFrameRequest\x12\x15\n\rviewport_name\x18\x01 \x01(\t\x12\r\n\x05width\x18\x02 \x01(\r\x12\x0e\n\x06height\x18\x03 \x01(\r\x12\x0e\n\x06\x66ormat\x18\x04 \x01(\t\"\xfe\x01\n\x15GetObservationRequest\x12\x12\n\nrobot_name\x18\x01 \x01(\t\x12\x12\n\nagent_name\x18\x02 \x01(\t\x12\x1b\n\x13include_joint_state\x18\x03 \x01(\x08\x12\x1b\n\x13include_agent_frame\x18\x04 \x01(\x08\x12\x19\n\x11include_telemetry\x18\x05 \x01(\x08\x12\x31\n\x07\x63\x61meras\x18\x06 \x03(\x0b\x32 .hazel.rpc.GetCameraFrameRequest\x12\x35\n\tviewports\x18\x07 \x03(\x0b\x32\".hazel.rpc.GetViewportFrameRequest\"\xd4\x02\n\x16GetObservationResponse\x12\x0f\n\x07success\x18\x01 \x01(\x08\x12\x0f\n\x07message\x18\x02 \x01(\t\x12\x14\n\x0ctimestamp_ms\x18\x03 \x01(\x04\x12\x14\n\x0c\x66rame_number\x18\x04 \x01(\r\x12*\n\x0bjoint_state\x18\x05 \x01(\x0b\x32\x15.hazel.rpc.JointState\x12*\n\x0b\x61gent_frame\x18\x06 \x01(\x0b\x32\x15.hazel.rpc.AgentFrame\x12,\n\ttelemetry\x18\x07 \x01(\x0b\x32\x19.hazel.rpc.TelemetryFrame\x12\x31\n\rcamera_frames\x18\x08 \x03(\x0b\x32\x1a.hazel.rpc.NamedImageFrame\x12\x33\n\x0fviewport_frames\x18\t \x03(\x0b\x32\x1a.hazel.rpc.NamedImageFrame\"F\n\x0bStepRequest\x12\x12\n\nagent_name\x18\x01 \x01(\t\x12\x0f\n\x07\x61\x63tions\x18\x02 \x03(\x02\x12\x12\n\ntimeout_ms\x18\x03 \x01(\r\"~\n\x0cStepResponse\x12\x0f\n\x07success\x18\x01 \x01(\x08\x12\x0f\n\x07message\x18\x02 \x01(\t\x12*\n\x0bobservation\x18\x03 \x01(\x0b\x32\x15.hazel.rpc.AgentFrame\x12 \n\x18physics_step_duration_us\x18\x04 \x01(\x04\x32\x87\x03\n\x0c\x41gentService\x12U\n\x0eGetAgentSchema\x12 .hazel.rpc.GetAgentSchemaRequest\x1a!.hazel.rpc.GetAgentSchemaResponse\x12U\n\x0eGetObservation\x12 .hazel.rpc.GetObservationRequest\x1a!.hazel.rpc.GetObservationResponse\x12\x45\n\x0bStreamAgent\x12\x1d.hazel.rpc.StreamAgentRequest\x1a\x15.hazel.rpc.AgentFrame0\x01\x12I\n\nResetAgent\x12\x1c.hazel.rpc.ResetAgentRequest\x1a\x1d.hazel.rpc.ResetAgentResponse\x12\x37\n\x04Step\x12\x16.hazel.rpc.StepRequest\x1a\x17.hazel.rpc.StepResponseB\x03\xf8\x01\x01\x62\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'agent_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  _globals['DESCRIPTOR']._loaded_options = None
+  _globals['DESCRIPTOR']._serialized_options = b'\370\001\001'
+  _globals['_AGENTSCHEMA']._serialized_start=85
+  _globals['_AGENTSCHEMA']._serialized_end=214
+  _globals['_GETAGENTSCHEMAREQUEST']._serialized_start=216
+  _globals['_GETAGENTSCHEMAREQUEST']._serialized_end=259
+  _globals['_GETAGENTSCHEMARESPONSE']._serialized_start=261
+  _globals['_GETAGENTSCHEMARESPONSE']._serialized_end=325
+  _globals['_STREAMAGENTREQUEST']._serialized_start=327
+  _globals['_STREAMAGENTREQUEST']._serialized_end=387
+  _globals['_DOMAINRANDOMIZATIONCONFIG']._serialized_start=390
+  _globals['_DOMAINRANDOMIZATIONCONFIG']._serialized_end=807
+  _globals['_RESETAGENTREQUEST']._serialized_start=809
+  _globals['_RESETAGENTREQUEST']._serialized_end=905
+  _globals['_RESETAGENTRESPONSE']._serialized_start=907
+  _globals['_RESETAGENTRESPONSE']._serialized_end=961
+  _globals['_AGENTFRAME']._serialized_start=964
+  _globals['_AGENTFRAME']._serialized_end=1099
+  _globals['_GETCAMERAFRAMEREQUEST']._serialized_start=1102
+  _globals['_GETCAMERAFRAMEREQUEST']._serialized_end=1237
+  _globals['_GETVIEWPORTFRAMEREQUEST']._serialized_start=1239
+  _globals['_GETVIEWPORTFRAMEREQUEST']._serialized_end=1334
+  _globals['_GETOBSERVATIONREQUEST']._serialized_start=1337
+  _globals['_GETOBSERVATIONREQUEST']._serialized_end=1591
+  _globals['_GETOBSERVATIONRESPONSE']._serialized_start=1594
+  _globals['_GETOBSERVATIONRESPONSE']._serialized_end=1934
+  _globals['_STEPREQUEST']._serialized_start=1936
+  _globals['_STEPREQUEST']._serialized_end=2006
+  _globals['_STEPRESPONSE']._serialized_start=2008
+  _globals['_STEPRESPONSE']._serialized_end=2134
+  _globals['_AGENTSERVICE']._serialized_start=2137
+  _globals['_AGENTSERVICE']._serialized_end=2528
+# @@protoc_insertion_point(module_scope)

luckyrobots-0.1.72/src/luckyrobots/grpc/generated/agent_pb2_grpc.py

@@ -0,0 +1,283 @@
+# 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 agent_pb2 as agent__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 agent_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 AgentServiceStub(object):
+    """Per-agent RL-style observation streaming (training / inference clients consume this).
+    """
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.GetAgentSchema = channel.unary_unary(
+                '/hazel.rpc.AgentService/GetAgentSchema',
+                request_serializer=agent__pb2.GetAgentSchemaRequest.SerializeToString,
+                response_deserializer=agent__pb2.GetAgentSchemaResponse.FromString,
+                _registered_method=True)
+        self.GetObservation = channel.unary_unary(
+                '/hazel.rpc.AgentService/GetObservation',
+                request_serializer=agent__pb2.GetObservationRequest.SerializeToString,
+                response_deserializer=agent__pb2.GetObservationResponse.FromString,
+                _registered_method=True)
+        self.StreamAgent = channel.unary_stream(
+                '/hazel.rpc.AgentService/StreamAgent',
+                request_serializer=agent__pb2.StreamAgentRequest.SerializeToString,
+                response_deserializer=agent__pb2.AgentFrame.FromString,
+                _registered_method=True)
+        self.ResetAgent = channel.unary_unary(
+                '/hazel.rpc.AgentService/ResetAgent',
+                request_serializer=agent__pb2.ResetAgentRequest.SerializeToString,
+                response_deserializer=agent__pb2.ResetAgentResponse.FromString,
+                _registered_method=True)
+        self.Step = channel.unary_unary(
+                '/hazel.rpc.AgentService/Step',
+                request_serializer=agent__pb2.StepRequest.SerializeToString,
+                response_deserializer=agent__pb2.StepResponse.FromString,
+                _registered_method=True)
+
+
+class AgentServiceServicer(object):
+    """Per-agent RL-style observation streaming (training / inference clients consume this).
+    """
+
+    def GetAgentSchema(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 GetObservation(self, request, context):
+        """Single-shot observation snapshot (unified observation surface).
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def StreamAgent(self, request, context):
+        """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.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def ResetAgent(self, request, context):
+        """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.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def Step(self, request, context):
+        """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.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+
+def add_AgentServiceServicer_to_server(servicer, server):
+    rpc_method_handlers = {
+            'GetAgentSchema': grpc.unary_unary_rpc_method_handler(
+                    servicer.GetAgentSchema,
+                    request_deserializer=agent__pb2.GetAgentSchemaRequest.FromString,
+                    response_serializer=agent__pb2.GetAgentSchemaResponse.SerializeToString,
+            ),
+            'GetObservation': grpc.unary_unary_rpc_method_handler(
+                    servicer.GetObservation,
+                    request_deserializer=agent__pb2.GetObservationRequest.FromString,
+                    response_serializer=agent__pb2.GetObservationResponse.SerializeToString,
+            ),
+            'StreamAgent': grpc.unary_stream_rpc_method_handler(
+                    servicer.StreamAgent,
+                    request_deserializer=agent__pb2.StreamAgentRequest.FromString,
+                    response_serializer=agent__pb2.AgentFrame.SerializeToString,
+            ),
+            'ResetAgent': grpc.unary_unary_rpc_method_handler(
+                    servicer.ResetAgent,
+                    request_deserializer=agent__pb2.ResetAgentRequest.FromString,
+                    response_serializer=agent__pb2.ResetAgentResponse.SerializeToString,
+            ),
+            'Step': grpc.unary_unary_rpc_method_handler(
+                    servicer.Step,
+                    request_deserializer=agent__pb2.StepRequest.FromString,
+                    response_serializer=agent__pb2.StepResponse.SerializeToString,
+            ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler(
+            'hazel.rpc.AgentService', rpc_method_handlers)
+    server.add_generic_rpc_handlers((generic_handler,))
+    server.add_registered_method_handlers('hazel.rpc.AgentService', rpc_method_handlers)
+
+
+ # This class is part of an EXPERIMENTAL API.
+class AgentService(object):
+    """Per-agent RL-style observation streaming (training / inference clients consume this).
+    """
+
+    @staticmethod
+    def GetAgentSchema(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.AgentService/GetAgentSchema',
+            agent__pb2.GetAgentSchemaRequest.SerializeToString,
+            agent__pb2.GetAgentSchemaResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)
+
+    @staticmethod
+    def GetObservation(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.AgentService/GetObservation',
+            agent__pb2.GetObservationRequest.SerializeToString,
+            agent__pb2.GetObservationResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)
+
+    @staticmethod
+    def StreamAgent(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.AgentService/StreamAgent',
+            agent__pb2.StreamAgentRequest.SerializeToString,
+            agent__pb2.AgentFrame.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)
+
+    @staticmethod
+    def ResetAgent(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.AgentService/ResetAgent',
+            agent__pb2.ResetAgentRequest.SerializeToString,
+            agent__pb2.ResetAgentResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)
+
+    @staticmethod
+    def Step(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.AgentService/Step',
+            agent__pb2.StepRequest.SerializeToString,
+            agent__pb2.StepResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)