hud 0.6.12.dev0__tar.gz → 0.6.13.dev1__tar.gz

{hud-0.6.12.dev0 → hud-0.6.13.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hud
-Version: 0.6.12.dev0
+Version: 0.6.13.dev1
 Summary: SDK for the HUD platform.
 Project-URL: Homepage, https://github.com/hud-evals/hud-python
 Project-URL: Bug Tracker, https://github.com/hud-evals/hud-python/issues
@@ -37,16 +37,16 @@ Requires-Python: <3.13,>=3.11
 Requires-Dist: anthropic>=0.78.0
 Requires-Dist: asyncssh>=2.23.0
 Requires-Dist: asyncvnc>=1.3.0
-Requires-Dist: fastmcp==3.0.2
+Requires-Dist: fastmcp==3.2.0
 Requires-Dist: google-genai
 Requires-Dist: httpx<1,>=0.23.0
 Requires-Dist: mcp<2.0,>=1.24.0
-Requires-Dist: openai==2.44.0
+Requires-Dist: openai>=2.45.0
 Requires-Dist: packaging>=21.0
 Requires-Dist: pillow>=11.0.0
 Requires-Dist: prompt-toolkit==3.0.51
 Requires-Dist: pydantic-settings<3,>=2.2
-Requires-Dist: pydantic<3,>=2.6
+Requires-Dist: pydantic<3,>=2.10
 Requires-Dist: questionary==2.1.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: typer>=0.9.0
@@ -60,7 +60,11 @@ Requires-Dist: browser-use>=0.11.13; extra == 'browseruse'
 Provides-Extra: daytona
 Requires-Dist: daytona>=0.100; extra == 'daytona'
 Provides-Extra: dev
+Requires-Dist: av>=12; extra == 'dev'
 Requires-Dist: dotenv>=0.9.9; extra == 'dev'
+Requires-Dist: gymnasium>=1.0; extra == 'dev'
+Requires-Dist: numpy>=1.24; extra == 'dev'
+Requires-Dist: openpi-client>=0.1.2; extra == 'dev'
 Requires-Dist: pyright==1.1.407; extra == 'dev'
 Requires-Dist: pytest-asyncio; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
@@ -71,6 +75,7 @@ Provides-Extra: modal
 Requires-Dist: modal>=1.0; extra == 'modal'
 Provides-Extra: robot
 Requires-Dist: av>=12; extra == 'robot'
+Requires-Dist: gymnasium>=1.0; extra == 'robot'
 Requires-Dist: numpy>=1.24; extra == 'robot'
 Requires-Dist: openpi-client>=0.1.2; extra == 'robot'
 Provides-Extra: train

{hud-0.6.12.dev0 → hud-0.6.13.dev1}/hud/__init__.py

@@ -32,6 +32,7 @@ from .eval import (
 from .telemetry.instrument import instrument
 from .train import TrainingClient
 from .types import Trace
+from .version import __version__
 
 _install_v5_compat()
 
@@ -56,11 +57,7 @@ __all__ = [
     "Taskset",
     "Trace",
     "TrainingClient",
+    "__version__",
     "connect",
     "instrument",
 ]
-
-try:
-    from .version import __version__
-except ImportError:
-    __version__ = "unknown"

{hud-0.6.12.dev0 → hud-0.6.13.dev1}/hud/agents/__init__.py

@@ -7,9 +7,10 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any, cast
 
+from hud.settings import settings
 from hud.types import AgentType
+from hud.utils.exceptions import HudAuthenticationError
 from hud.utils.gateway import (
-    build_gateway_client,
     gateway_model_aliases,
     list_gateway_models,
     normalize_gateway_model_id,
@@ -30,14 +31,29 @@ if TYPE_CHECKING:
 def create_agent(model: str, **kwargs: Any) -> GatewayAgent:
     """Create an agent routed through the HUD gateway.
 
-    For direct API access with provider API keys, instantiate the agent classes directly.
+    Leaves ``model_client`` unset so provider agent constructors build the HUD
+    gateway client locally, while :class:`~hud.eval.runtime.HostedRuntime` can
+    serialize the config and rebuild the client remotely. Explicitly supplied
+    clients remain custom/BYOK and are not serializable.
+
+    For direct API access with provider API keys, instantiate the agent classes
+    directly.
     """
+    direct_credentials = [name for name in ("api_key", "base_url") if name in kwargs]
+    if direct_credentials:
+        names = ", ".join(direct_credentials)
+        raise ValueError(
+            f"create_agent routes through the HUD gateway and does not accept {names}; "
+            "instantiate the provider agent directly for custom/BYOK credentials"
+        )
+    if not settings.api_key:
+        raise HudAuthenticationError("HUD_API_KEY is required to create a gateway agent")
+
     requested_model = model
     model = normalize_gateway_model_id(model)
     agent_type = next((candidate for candidate in AgentType if candidate.value == model), None)
     if agent_type is not None:
         model_id = model
-        provider_name = agent_type.gateway_provider
     else:
         try:
             gateway_models = list_gateway_models()
@@ -69,7 +85,6 @@ def create_agent(model: str, **kwargs: Any) -> GatewayAgent:
                 except ValueError as exc:
                     raise ValueError(f"Model '{model}' has invalid agent type metadata") from exc
                 model_id = gateway_model.model_name or model
-                provider_name = gateway_model.provider.name or "openai"
                 break
         else:
             import difflib
@@ -95,7 +110,6 @@ def create_agent(model: str, **kwargs: Any) -> GatewayAgent:
             raise ValueError(f"Model {requested_model!r} not found in {source}.{hint}")
 
     kwargs.setdefault("model", model_id)
-    kwargs.setdefault("model_client", build_gateway_client(provider_name))
     # cls/config_cls are matched unions; the pairing is correct by construction.
     config = agent_type.config_cls(**kwargs)
     return agent_type.cls(cast("Any", config))

{hud-0.6.12.dev0 → hud-0.6.13.dev1}/hud/agents/claude/tools/computer.py

@@ -278,13 +278,17 @@ class ClaudeComputerTool(RFBTool):
             x0, y0, x1, y1 = (int(v) for v in region_seq)
         except (TypeError, ValueError):
             return tool_err("region must contain 4 integers")
-        png = await self.client.screenshot_png()
-        cropped = _crop_png(png, (x0, y0, x1, y1))
+        screenshot, _ = await self.client.screenshot_png("image/png")
+        cropped, mime_type = _crop_png(
+            screenshot,
+            (x0, y0, x1, y1),
+            self.screenshot_mime_type,
+        )
         return MCPToolResult(
             content=[
                 mcp_types.ImageContent(
                     type="image",
-                    mimeType="image/png",
+                    mimeType=mime_type,
                     data=base64.b64encode(cropped).decode("ascii"),
                 )
             ],
@@ -349,14 +353,21 @@ def _drag_path(arguments: dict[str, Any]) -> list[tuple[int, int]]:
     return path
 
 
-def _crop_png(png: bytes, region: tuple[int, int, int, int]) -> bytes:
+def _crop_png(
+    png: bytes,
+    region: tuple[int, int, int, int],
+    mime_type: str,
+) -> tuple[bytes, str]:
     from PIL import Image
 
     image = Image.open(BytesIO(png))
     cropped = image.crop(region)
     buf = BytesIO()
-    cropped.save(buf, format="PNG")
-    return buf.getvalue()
+    if mime_type == "image/webp":
+        cropped.save(buf, format="WEBP", quality=85)
+    else:
+        cropped.save(buf, format="PNG")
+    return buf.getvalue(), mime_type
 
 
 __all__ = ["CLAUDE_COMPUTER_SPECS", "ClaudeComputerTool"]

{hud-0.6.12.dev0 → hud-0.6.13.dev1}/hud/agents/claude/tools/tests/test_computer.py

@@ -5,12 +5,18 @@ computer-use action dispatch (translation to RFB primitives), without a live VNC
 
 from __future__ import annotations
 
+from io import BytesIO
 from types import SimpleNamespace
 from typing import Any
+from unittest.mock import AsyncMock, patch
+
+import mcp.types as mcp_types
+from PIL import Image
 
 from hud.agents.claude.tools.computer import (
     CLAUDE_COMPUTER_SPECS,
     ClaudeComputerTool,
+    _crop_png,
     _hold_keys,
     _split_keys,
     _translate_key,
@@ -25,6 +31,7 @@ class RecordingComputer(ClaudeComputerTool):
 
     def __init__(self) -> None:
         self.calls: list[tuple[Any, ...]] = []
+        self.screenshot_mime_type = "image/webp"
         self.client = SimpleNamespace(width=200, height=100)
 
     async def screenshot(self) -> Any:
@@ -147,3 +154,29 @@ async def test_unsupported_action_errors() -> None:
     result = await tool.execute({"action": "frobnicate"})
     assert result.isError
     assert "unsupported" in result_text(result).lower()
+
+
+def test_crop_reports_encoded_mime_type() -> None:
+    source = BytesIO()
+    Image.effect_noise((128, 128), 100).convert("RGB").save(source, format="PNG")
+
+    cropped, mime_type = _crop_png(source.getvalue(), (0, 0, 128, 128), "image/webp")
+
+    assert mime_type == "image/webp"
+    assert cropped.startswith(b"RIFF")
+
+
+async def test_zoom_reports_encoded_mime_type() -> None:
+    tool = RecordingComputer()
+    tool.client.screenshot_png = AsyncMock(return_value=(b"png", "image/png"))
+
+    with patch(
+        "hud.agents.claude.tools.computer._crop_png",
+        return_value=(b"webp", "image/webp"),
+    ) as crop:
+        result = await tool._zoom({"region": [0, 0, 10, 10]})
+
+    tool.client.screenshot_png.assert_awaited_once_with("image/png")
+    crop.assert_called_once_with(b"png", (0, 0, 10, 10), "image/webp")
+    image = next(block for block in result.content if isinstance(block, mcp_types.ImageContent))
+    assert image.mimeType == "image/webp"

{hud-0.6.12.dev0 → hud-0.6.13.dev1}/hud/agents/misc/response_automation.py

@@ -85,7 +85,6 @@ async def _determine_response(
         ],
         reasoning={"effort": "low"},
         max_output_tokens=256,
-        extra_headers={"Trace-Id": ""},
     )
 
     text_parts: list[str] = []

{hud-0.6.12.dev0 → hud-0.6.13.dev1}/hud/agents/openai/agent.py

@@ -33,7 +33,7 @@ from hud.utils import gateway
 from .tools import OpenAIComputerTool, OpenAIMCPProxyTool, OpenAIShellTool
 from .tools.base import format_openai_result
 from .tools.coding import shell_output
-from .tools.computer import last_image_data
+from .tools.computer import last_image_content
 
 if TYPE_CHECKING:
     import mcp.types as mcp_types
@@ -104,8 +104,8 @@ class OpenAIAgent(ToolAgent[ResponseInputItemParam, OpenAIConfig]):
         tool = state.tools.get(call.name)
 
         if isinstance(tool, OpenAIComputerTool):
-            screenshot = last_image_data(result)
-            if not screenshot:
+            screenshot = last_image_content(result)
+            if screenshot is None:
                 logger.warning("Computer tool result missing screenshot for call %s", call.name)
                 return None
             output = ComputerCallOutput(
@@ -115,7 +115,9 @@ class OpenAIAgent(ToolAgent[ResponseInputItemParam, OpenAIConfig]):
                     "Any",
                     {
                         "type": "computer_screenshot",
-                        "image_url": f"data:image/png;base64,{screenshot}",
+                        "image_url": (
+                            f"data:{screenshot.mimeType or 'image/png'};base64,{screenshot.data}"
+                        ),
                         "detail": "original",
                     },
                 ),

{hud-0.6.12.dev0 → hud-0.6.13.dev1}/hud/agents/openai/tools/base.py

@@ -12,7 +12,6 @@ from openai.types.responses import (
     ResponseInputFileContentParam,
     ResponseInputImageContentParam,
     ResponseInputTextContentParam,
-    ResponseInputTextParam,
 )
 from openai.types.responses.response_input_param import FunctionCallOutput, ResponseInputItemParam
 
@@ -76,7 +75,7 @@ def format_openai_result(call: MCPToolCall, result: MCPToolResult) -> ResponseIn
                 logger.warning("Unknown content block type: %s", type(block))
 
     if not output_items:
-        output_items.append(ResponseInputTextParam(type="input_text", text=""))
+        output_items.append(ResponseInputTextContentParam(type="input_text", text=""))
 
     return cast(
         "ResponseInputItemParam",

{hud-0.6.12.dev0 → hud-0.6.13.dev1}/hud/agents/openai/tools/coding.py

@@ -7,7 +7,6 @@ from typing import Any, cast
 import mcp.types as mcp_types
 
 from hud.agents.tools import SSHTool
-from hud.agents.tools.base import result_text
 from hud.types import MCPToolResult
 
 from .base import OpenAIToolSpec
@@ -17,6 +16,9 @@ OPENAI_SHELL_SPEC = OpenAIToolSpec(
     api_name="shell",
 )
 
+MAX_SHELL_OUTPUT_LENGTH = 10 * 1024 * 1024
+TRUNCATION_MARKER = "[truncated]"
+
 
 class OpenAIShellTool(SSHTool):
     name = "shell"
@@ -32,14 +34,31 @@ class OpenAIShellTool(SSHTool):
         return {"type": "shell", "environment": {"type": "local"}}
 
     async def execute(self, arguments: dict[str, Any]) -> MCPToolResult:
+        requested_limit = arguments.get("max_output_length")
+        if requested_limit is None:
+            max_output_length = MAX_SHELL_OUTPUT_LENGTH
+        elif (
+            isinstance(requested_limit, bool)
+            or not isinstance(requested_limit, int)
+            or requested_limit <= 0
+        ):
+            text = "max_output_length must be a positive integer"
+            return _shell_result(
+                [text],
+                is_error=True,
+                structured={"output": [shell_output("", text, 1)]},
+            )
+        else:
+            max_output_length = min(requested_limit, MAX_SHELL_OUTPUT_LENGTH)
+
         def invalid_commands_result() -> MCPToolResult:
             text = "commands must be a list of strings"
             return _shell_result(
-                text,
+                [text],
                 is_error=True,
                 structured={
                     "output": [shell_output("", text, 1)],
-                    "max_output_length": arguments.get("max_output_length"),
+                    "max_output_length": max_output_length,
                 },
             )
 
@@ -54,7 +73,7 @@ class OpenAIShellTool(SSHTool):
         command_list = cast("list[str]", raw_commands)
 
         outputs: list[dict[str, Any]] = []
-        text_parts: list[str] = []
+        display_outputs: list[str] = []
         is_error = False
         env_arguments: dict[str, Any] = {}
         timeout_ms = arguments.get("timeout_ms")
@@ -66,40 +85,64 @@ class OpenAIShellTool(SSHTool):
                 full_cmd = f"timeout {int(env_arguments['timeout_seconds'])} {command}"
             else:
                 full_cmd = command
-            result = await self.bash(full_cmd)
-            text = result_text(result)
-            if result.isError:
-                outputs.append(shell_output("", text, 1))
-                is_error = True
-            else:
-                outputs.append(shell_output(text, "", 0))
-            if text:
-                text_parts.append(text)
+            completed = await self.client.conn.run(full_cmd, check=False)
+            stdout = completed.stdout if isinstance(completed.stdout, str) else ""
+            stderr = completed.stderr if isinstance(completed.stderr, str) else ""
+            exit_code = completed.exit_status if completed.exit_status is not None else 1
+            stdout, stderr = _bound_output(stdout, stderr, max_output_length)
+            outputs.append(shell_output(stdout, stderr, exit_code))
+            display_outputs.append(stdout + stderr)
+            is_error = is_error or bool(exit_code)
 
         return _shell_result(
-            "\n".join(text_parts),
+            display_outputs,
             is_error=is_error,
             structured={
                 "output": outputs,
-                "max_output_length": arguments.get("max_output_length"),
+                "max_output_length": max_output_length,
             },
         )
 
 
 def _shell_result(
-    text: str,
+    texts: list[str],
     *,
     is_error: bool = False,
     structured: dict[str, Any] | None = None,
 ) -> MCPToolResult:
     payload = {"provider_tool": "shell", **(structured or {})}
     return MCPToolResult(
-        content=[mcp_types.TextContent(type="text", text=text)] if text else [],
+        content=[mcp_types.TextContent(type="text", text=text) for text in texts if text],
         isError=is_error,
         structuredContent=payload,
     )
 
 
+def _bound_output(stdout: str, stderr: str, limit: int) -> tuple[str, str]:
+    total_length = len(stdout) + len(stderr)
+    if total_length <= limit:
+        return stdout, stderr
+
+    marker = TRUNCATION_MARKER[:limit]
+    available = limit - len(marker)
+    prefix_length = (available + 1) // 2
+    suffix_length = available // 2
+
+    stdout_prefix = stdout[:prefix_length]
+    stderr_prefix = stderr[: max(0, prefix_length - len(stdout))]
+    stderr_suffix = stderr[-suffix_length:] if suffix_length else ""
+    stdout_suffix_length = max(0, suffix_length - len(stderr))
+    stdout_suffix = stdout[-stdout_suffix_length:] if stdout_suffix_length else ""
+
+    if len(stdout_prefix) + len(stdout_suffix) < len(stdout):
+        stdout = stdout_prefix + marker + stdout_suffix
+        stderr = stderr_prefix + stderr_suffix
+    else:
+        stdout = stdout_prefix + stdout_suffix
+        stderr = stderr_prefix + marker + stderr_suffix
+    return stdout, stderr
+
+
 def shell_output(stdout: str, stderr: str, exit_code: int) -> dict[str, Any]:
     return {
         "stdout": stdout,

{hud-0.6.12.dev0 → hud-0.6.13.dev1}/hud/agents/openai/tools/computer.py

@@ -23,9 +23,15 @@ OPENAI_COMPUTER_SPEC = OpenAIToolSpec(
 
 def last_image_data(result: MCPToolResult) -> str | None:
     """Base64 data of the most recent screenshot block in a tool result."""
+    image = last_image_content(result)
+    return image.data if image is not None else None
+
+
+def last_image_content(result: MCPToolResult) -> mcp_types.ImageContent | None:
+    """Most recent screenshot block in a tool result."""
     for block in reversed(result.content):
         if isinstance(block, mcp_types.ImageContent):
-            return block.data
+            return block
     return None
 
 

{hud-0.6.12.dev0 → hud-0.6.13.dev1}/hud/agents/openai_compatible/tools/filesystem.py

@@ -66,9 +66,6 @@ class ReadTool(_FilesystemTool):
         path = arguments.get("filePath")
         if not isinstance(path, str) or not path:
             raise ValueError("filePath is required")
-        # Map once so the directory predicate and the file read agree on
-        # the same workspace-anchored path.
-        path = self.client.map_path(path)
         offset = _read_offset(arguments.get("offset"))
         limit = _positive_int(arguments.get("limit"), default=DEFAULT_READ_LIMIT, name="limit")
         if not (await self.bash(f"test -d {shlex.quote(path)}")).isError:
@@ -196,9 +193,6 @@ class EditTool(_FilesystemTool):
         path = arguments.get("filePath")
         if not isinstance(path, str) or not path:
             raise ValueError("filePath is required")
-        # Map once so existence checks, mkdir, and the write all target
-        # the same workspace-anchored path.
-        path = self.client.map_path(path)
         old = arguments.get("oldString")
         new = arguments.get("newString")
         if not isinstance(old, str):
@@ -258,7 +252,6 @@ class WriteTool(_FilesystemTool):
         path = arguments.get("filePath")
         if not isinstance(path, str) or not path:
             raise ValueError("filePath is required")
-        path = self.client.map_path(path)
         content = arguments.get("content")
         if not isinstance(content, str):
             raise ValueError("content is required")
@@ -294,7 +287,7 @@ class GrepTool(_FilesystemTool):
         pattern = arguments.get("pattern")
         if not isinstance(pattern, str):
             raise ValueError("pattern is required")
-        path = self.client.map_path(str(arguments.get("path") or "."))
+        path = str(arguments.get("path") or ".")
         cmd = f"grep -rn {shlex.quote(pattern)} {shlex.quote(path)}"
         include = arguments.get("include")
         if isinstance(include, str) and include:
@@ -318,7 +311,7 @@ class GlobTool(_FilesystemTool):
         pattern = arguments.get("pattern")
         if not isinstance(pattern, str):
             raise ValueError("pattern is required")
-        path = self.client.map_path(str(arguments.get("path") or "."))
+        path = str(arguments.get("path") or ".")
         return await self.bash(f"find {shlex.quote(path)} -name {shlex.quote(pattern)}")
 
 

hud-0.6.13.dev1/hud/agents/robot/__init__.py

@@ -0,0 +1,39 @@
+"""Agent-side robot harness: drive a ``robot`` env with a VLA policy.
+
+- :class:`~.agent.RobotAgent` — the harness: connects to the ``robot``
+  capability (claiming a slot token from the setup step when present), reads the contract,
+  drives one scalar connection with an open-loop chunk queue. Subclass and
+  set ``self.model`` + ``self.adapter``.
+- :class:`~.model.Model` / :class:`~.model.LeRobotModel` /
+  :class:`~.model.RemoteModel` — the policy and its inference mechanics.
+- :class:`~.adapter.Adapter` / :class:`~.adapter.LeRobotAdapter` /
+  :class:`~.adapter.OpenPIAdapter` — env <-> policy space translation.
+- :class:`~.batching.BatchedAgent` — many concurrent single-env rollouts
+  sharing one batched model.
+- :class:`~.dataset.DatasetWriter` — opt-in LeRobot v3 dataset recording
+  (``agent.save = True``).
+
+This subpackage needs the ``robot`` extra (``pip install 'hud[robot]'``).
+"""
+
+from __future__ import annotations
+
+from .adapter import Adapter, LeRobotAdapter, OpenPIAdapter
+from .agent import ROBOT_PROTOCOL, RobotAgent
+from .batching import BatchedAgent, BatchedModel
+from .dataset import DatasetWriter
+from .model import LeRobotModel, Model, RemoteModel
+
+__all__ = [
+    "ROBOT_PROTOCOL",
+    "Adapter",
+    "BatchedAgent",
+    "BatchedModel",
+    "DatasetWriter",
+    "LeRobotAdapter",
+    "LeRobotModel",
+    "Model",
+    "OpenPIAdapter",
+    "RemoteModel",
+    "RobotAgent",
+]

hud-0.6.13.dev1/hud/agents/robot/adapter.py

@@ -0,0 +1,118 @@
+"""Translate observations and actions between env and policy spaces.
+
+The loop calls ``bind``, ``reset``, ``adapt_observation``, and the action hooks.
+Use :class:`LeRobotAdapter` for LeRobot models; subclass for custom wiring;
+``adapter=None`` for pass-through.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+#: A policy-emitted action / chunk array (the robot stack's shared alias).
+ActionArray = NDArray[np.floating[Any]]
+
+#: Image types the bundled adapters treat as cameras (vs the state vector).
+IMAGE_TYPES = ("rgb", "bgr", "gray", "depth")
+
+
+class Adapter:
+    """Translate between an env's observation/action spaces and a policy's.
+
+    Driven by :class:`~hud.agents.robot.agent.RobotAgent`: :meth:`bind` once
+    after connect, :meth:`reset` once per episode, then :meth:`adapt_observation`
+    per inference and the action hooks per chunk/step. Construct with the
+    policy's image-slot names; everything env-side is learned in :meth:`bind`.
+    """
+
+    def __init__(
+        self,
+        *,
+        model_image_keys: list[str] | None = None,
+        chunk_size: int | None = None,
+    ) -> None:
+        #: The policy's ordered image-slot names (model side; known at load time).
+        self.model_image_keys: list[str] = list(model_image_keys or [])
+        #: Open-loop horizon: how many predicted actions to execute before re-querying.
+        #: ``None`` = full model chunk. Applied by :class:`~.agent.RobotAgent`, not here —
+        #: so subclass ``adapt_chunk`` overrides stay free of truncation duty.
+        self.chunk_size: int | None = chunk_size
+        #: The env's action feature and observation layout (set in :meth:`bind`).
+        self.action_space: dict[str, Any] = {}
+        self.image_keys: list[str] = []
+        self.state_key: str | None = None
+
+    def bind(self, action_space: dict[str, Any], observation_space: dict[str, Any]) -> None:
+        """Learn the env's layout from the contract (``client.spaces()``): image
+        features become the camera keys (in contract order), the first non-image
+        feature is the state. Override to derive extra env-side parameters."""
+        self.action_space = action_space or {}
+        self.image_keys = [n for n, f in observation_space.items() if f.get("type") in IMAGE_TYPES]
+        self.state_key = next(
+            (n for n, f in observation_space.items() if f.get("type") not in IMAGE_TYPES), None
+        )
+
+    def reset(self) -> None:
+        """Override only if the adapter is stateful across steps within an episode."""
+
+    def adapt_observation(self, obs: dict[str, Any], prompt: str) -> Any:
+        """Translate an env observation + task prompt into the policy's input."""
+        raise NotImplementedError
+
+    def adapt_chunk(self, chunk: ActionArray, obs: dict[str, Any]) -> ActionArray:
+        """Translate a freshly-inferred ``[T, A]`` chunk to env space, given the
+        (per-slot) query-time observation it was inferred from (default identity).
+
+        Called once per slot at inference time, so a chunk expressed relative to
+        the query state — e.g. joint *deltas* to be added to the query-time
+        joints — converts in one shot.
+        """
+        return chunk
+
+    def adapt_action(self, action: ActionArray, obs: dict[str, Any]) -> ActionArray:
+        """Per-step execution-time hook on the popped action (default identity)."""
+        return action
+
+
+class LeRobotAdapter(Adapter):
+    """Vanilla LeRobot adapter for a standard image/state env, single or batched.
+
+    Maps env cameras onto the model's image slots in order and converts HWC
+    ``uint8`` to CHW ``float`` in ``[0, 1]``; state and prompt pass through.
+    A batched observation (state ``[N, S]``) maps in one go — cameras become
+    ``[N, C, H, W]`` and the shared task is repeated to ``N``. Actions are
+    identity (postprocess already returns env-space actions).
+    """
+
+    def adapt_observation(self, obs: dict[str, Any], prompt: str) -> dict[str, Any]:
+        import torch  # pyright: ignore[reportMissingImports]
+
+        torch_mod: Any = torch  # torch ships no stubs; keep strict mode quiet
+        data = obs["data"]
+        state = np.asarray(data[self.state_key], dtype=np.float32)
+        batched = state.ndim > 1  # [N, S] vs [S]
+        batch: dict[str, Any] = {
+            "observation.state": torch_mod.from_numpy(state),
+            "task": [prompt] * len(state) if batched else prompt,
+        }
+        for model_key, env_key in zip(self.model_image_keys, self.image_keys, strict=False):
+            img = torch_mod.from_numpy(np.asarray(data[env_key]))
+            perm = (0, 3, 1, 2) if batched else (2, 0, 1)
+            batch[model_key] = img.permute(*perm).float() / 255.0
+        return batch
+
+
+class OpenPIAdapter(Adapter):
+    """Unwraps ``obs['data']`` to OpenPI wire keys and attaches the prompt;
+    actions are pass-through."""
+
+    def adapt_observation(self, obs: dict[str, Any], prompt: str) -> dict[str, Any]:
+        out = dict(obs["data"])
+        out.setdefault("prompt", prompt)
+        return out
+
+
+__all__ = ["ActionArray", "Adapter", "LeRobotAdapter", "OpenPIAdapter"]