inspect-robots-agent 0.1.0__py3-none-any.whl

inspect_robots_agent/__init__.py

@@ -0,0 +1,28 @@
+"""inspect-robots-agent — frontier LLMs as first-class Inspect Robots policies.
+
+An LLM behind any OpenAI-compatible API (OpenRouter, OpenAI, local
+vLLM/Ollama, Anthropic's compat endpoint) drives whatever embodiment it is
+paired with: each tool call becomes one smooth, approver-checked action
+chunk. Registered as the policy ``agent``::
+
+    inspect-robots "pick up the cube" --policy agent \
+        -P model=anthropic/claude-fable-5 --embodiment cubepick
+
+or programmatically::
+
+    from inspect_robots import eval
+    from inspect_robots_agent import LLMAgentPolicy
+
+    eval("my-task", LLMAgentPolicy(model="openai/gpt-5.2"), "cubepick")
+
+The policy is discovered via the ``inspect_robots.policies`` entry point, so
+it shows up in ``inspect-robots list policies`` without being imported first.
+"""
+
+from __future__ import annotations
+
+from inspect_robots_agent.policy import AgentPolicyConfig, LLMAgentPolicy, agent_policy
+
+__all__ = ["AgentPolicyConfig", "LLMAgentPolicy", "agent_policy"]
+
+__version__ = "0.1.0"

inspect_robots_agent/_llm.py

@@ -0,0 +1,186 @@
+"""OpenAI-compatible chat client + provider resolution (plan 0008 §4a).
+
+No provider SDKs: one ``httpx`` client speaking the chat-completions wire
+format covers OpenRouter, OpenAI, local vLLM/Ollama, and Anthropic's
+OpenAI-compat endpoint — the same "speak the protocol, don't import the
+package" doctrine as the xpolicylab plugin.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from inspect_robots.errors import ConfigError
+
+ENV_MODEL = "INSPECT_ROBOTS_MODEL"
+
+_ANTHROPIC_BASE = "https://api.anthropic.com/v1"
+_OPENAI_BASE = "https://api.openai.com/v1"
+_OPENROUTER_BASE = "https://openrouter.ai/api/v1"
+_OPENROUTER_KEY = "OPENROUTER_API_KEY"
+
+
+@dataclass(frozen=True)
+class Provider:
+    """A resolved OpenAI-compatible endpoint: where, with which key, which model."""
+
+    base_url: str
+    api_key: str
+    model: str
+
+
+def resolve_provider(
+    model: str | None,
+    base_url: str | None,
+    api_key_env: str | None,
+    env: Mapping[str, str],
+) -> Provider:
+    """The key/base-url ladder (plan 0008 §4a); first match wins.
+
+    1. Explicit ``base_url`` — any OpenAI-compatible endpoint; the key comes
+       from ``api_key_env`` (default ``OPENROUTER_API_KEY``), and a missing
+       key is allowed (local vLLM/Ollama endpoints are typically keyless).
+    2. ``anthropic/*`` model + ``ANTHROPIC_API_KEY`` — the Anthropic compat
+       endpoint (provider prefix stripped from the model id).
+    3. ``openai/*`` model + ``OPENAI_API_KEY`` — OpenAI (prefix stripped).
+    4. ``OPENROUTER_API_KEY`` — OpenRouter, which takes the full
+       ``provider/model`` string.
+
+    Anything else is a guided [`ConfigError`][inspect_robots.errors.ConfigError]
+    naming the fixes — never a traceback at the user.
+    """
+    if not model:
+        raise ConfigError(
+            "no model configured for the agent policy.\n"
+            f"fix: pass -P model=provider/model (e.g. anthropic/claude-fable-5) "
+            f"or set ${ENV_MODEL}"
+        )
+    if base_url:
+        key_env = api_key_env or _OPENROUTER_KEY
+        return Provider(base_url=base_url.rstrip("/"), api_key=env.get(key_env, ""), model=model)
+    provider_prefix, _, bare_model = model.partition("/")
+    if provider_prefix == "anthropic" and (key := env.get("ANTHROPIC_API_KEY")):
+        return Provider(base_url=_ANTHROPIC_BASE, api_key=key, model=bare_model)
+    if provider_prefix == "openai" and (key := env.get("OPENAI_API_KEY")):
+        return Provider(base_url=_OPENAI_BASE, api_key=key, model=bare_model)
+    if key := env.get(_OPENROUTER_KEY):
+        return Provider(base_url=_OPENROUTER_BASE, api_key=key, model=model)
+    raise ConfigError(
+        f"no API key found for model {model!r}.\n"
+        f"fix: set ${_OPENROUTER_KEY} (works for any model), or the provider's "
+        "key ($ANTHROPIC_API_KEY for anthropic/*, $OPENAI_API_KEY for openai/*), "
+        "or pass -P base_url=... (+ -P api_key_env=NAME) for a custom endpoint"
+    )
+
+
+@dataclass(frozen=True)
+class ToolCall:
+    """One tool invocation the model asked for; ``arguments`` is raw JSON text."""
+
+    id: str
+    name: str
+    arguments: str
+
+
+@dataclass(frozen=True)
+class AssistantMessage:
+    """The parsed ``choices[0].message`` of a chat completion."""
+
+    content: str | None
+    tool_calls: tuple[ToolCall, ...]
+
+    def raw(self) -> dict[str, Any]:
+        """The wire-format dict to append back onto the conversation."""
+        message: dict[str, Any] = {"role": "assistant", "content": self.content}
+        if self.tool_calls:
+            message["tool_calls"] = [
+                {
+                    "id": c.id,
+                    "type": "function",
+                    "function": {"name": c.name, "arguments": c.arguments},
+                }
+                for c in self.tool_calls
+            ]
+        return message
+
+
+class ChatClient:
+    """Blocking chat-completions client with bounded retry on transient failures.
+
+    Retries 429/5xx and transport errors with exponential backoff; a 4xx is
+    our request's fault and fails immediately. Persistent failure raises
+    ``RuntimeError``, which the rollout wraps as ``PolicyError``.
+    """
+
+    def __init__(
+        self,
+        provider: Provider,
+        *,
+        timeout_s: float = 120.0,
+        max_retries: int = 3,
+        backoff_s: float = 1.0,
+        transport: httpx.BaseTransport | None = None,
+    ):
+        self._provider = provider
+        self._max_retries = max_retries
+        self._backoff_s = backoff_s
+        headers = {}
+        if provider.api_key:
+            headers["Authorization"] = f"Bearer {provider.api_key}"
+        self._http = httpx.Client(
+            base_url=provider.base_url,
+            headers=headers,
+            timeout=timeout_s,
+            transport=transport,
+        )
+
+    def complete(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]],
+        temperature: float | None = None,
+    ) -> AssistantMessage:
+        body: dict[str, Any] = {"model": self._provider.model, "messages": messages}
+        if tools:
+            body["tools"] = tools
+        if temperature is not None:
+            body["temperature"] = temperature
+
+        last_error = "unknown error"
+        for attempt in range(self._max_retries):
+            try:
+                response = self._http.post("/chat/completions", json=body)
+            except httpx.TransportError as exc:
+                last_error = str(exc)
+            else:
+                if response.status_code == 200:
+                    return _parse_message(response.json())
+                last_error = f"HTTP {response.status_code}: {response.text[:500]}"
+                if response.status_code not in (429,) and response.status_code < 500:
+                    # A 4xx is our request's fault; retrying cannot help.
+                    raise RuntimeError(f"LLM request rejected — {last_error}")
+            if attempt + 1 < self._max_retries:
+                time.sleep(self._backoff_s * 2**attempt)
+        raise RuntimeError(f"LLM request failed after {self._max_retries} attempts — {last_error}")
+
+    def close(self) -> None:
+        self._http.close()
+
+
+def _parse_message(payload: dict[str, Any]) -> AssistantMessage:
+    message = payload["choices"][0]["message"]
+    calls = tuple(
+        ToolCall(
+            id=str(c["id"]),
+            name=str(c["function"]["name"]),
+            arguments=str(c["function"]["arguments"]),
+        )
+        for c in message.get("tool_calls") or []
+    )
+    content = message.get("content")
+    return AssistantMessage(content=content if content is None else str(content), tool_calls=calls)

inspect_robots_agent/_png.py

@@ -0,0 +1,50 @@
+"""Minimal stdlib PNG encoder for camera frames (no Pillow dependency).
+
+LLM APIs take images as base64 data URLs; this encodes an ``(H, W, C)``
+uint8/float array as an uncompressed-filter PNG using only zlib + struct.
+"""
+
+from __future__ import annotations
+
+import base64
+import struct
+import zlib
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+
+_COLOR_TYPE_BY_CHANNELS = {1: 0, 3: 2, 4: 6}
+
+
+def _chunk(tag: bytes, data: bytes) -> bytes:
+    return struct.pack(">I", len(data)) + tag + data + struct.pack(">I", zlib.crc32(tag + data))
+
+
+def encode_png(image: npt.NDArray[Any]) -> bytes:
+    """Encode an ``(H, W)`` or ``(H, W, {1,3,4})`` array as PNG bytes.
+
+    Float arrays are assumed normalized to [0, 1] and scaled; everything else
+    is cast to uint8.
+    """
+    arr = np.asarray(image)
+    if np.issubdtype(arr.dtype, np.floating):
+        arr = (np.clip(arr, 0.0, 1.0) * 255.0).round()
+    arr = np.ascontiguousarray(arr.astype(np.uint8))
+    if arr.ndim == 2:
+        arr = arr[:, :, np.newaxis]
+    height, width, channels = arr.shape
+    color_type = _COLOR_TYPE_BY_CHANNELS[channels]
+    header = struct.pack(">IIBBBBB", width, height, 8, color_type, 0, 0, 0)
+    raw = b"".join(b"\x00" + arr[row].tobytes() for row in range(height))
+    return (
+        b"\x89PNG\r\n\x1a\n"
+        + _chunk(b"IHDR", header)
+        + _chunk(b"IDAT", zlib.compress(raw))
+        + _chunk(b"IEND", b"")
+    )
+
+
+def png_data_url(image: npt.NDArray[Any]) -> str:
+    """The ``data:image/png;base64,...`` form LLM APIs accept inline."""
+    return "data:image/png;base64," + base64.b64encode(encode_png(image)).decode("ascii")

inspect_robots_agent/_tools.py

@@ -0,0 +1,282 @@
+"""The agent's tool surface over a bound action space (plan 0008 §4b/§4c).
+
+Tools are generated from the embodiment's spaces — the plugin never knows
+what a "YAM" or an "arm" is. The control mode picks the motion tool:
+
+- Absolute-target modes (``joint_pos``, ``eef_abs_pose``): ``move_joints``
+  with named partial targets, linearly interpolated from the current
+  observed state; hold-still repeats the current state.
+- Displacement modes (``eef_delta_pos``, ``eef_delta_pose``,
+  ``joint_delta``): ``move_by`` splits the requested displacement evenly
+  across the chunk's steps; hold-still is all zeros.
+
+Tool mistakes (unknown label, non-finite value, bad duration, malformed
+JSON) come back as structured error strings the LLM sees and can correct —
+never exceptions. Unsupported configurations fail at build (= ``bind``)
+time with a clear message.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+
+from inspect_robots.spaces import Box, ObservationSpace
+from inspect_robots.types import Action, ActionChunk, Observation
+
+_ABSOLUTE_MODES = frozenset({"joint_pos", "eef_abs_pose"})
+_DISPLACEMENT_MODES = frozenset({"eef_delta_pos", "eef_delta_pose", "joint_delta"})
+_POSE_MODES = frozenset({"eef_abs_pose", "eef_delta_pose"})
+_SAFE_ROT = frozenset({"none", "rot6d"})
+
+_FALLBACK_HZ = 10.0
+_MAX_DURATION_S = 10.0
+
+
+class ToolsetError(Exception):
+    """An action space / observation space this toolset cannot drive."""
+
+
+@dataclass(frozen=True)
+class ToolResult:
+    """One executed tool call: an action chunk to play, or an error for the LLM.
+
+    Exactly one of ``chunk``/``error`` is set. ``note`` is the human/LLM-facing
+    confirmation text for successful calls.
+    """
+
+    chunk: ActionChunk | None = None
+    error: str | None = None
+    note: str = ""
+
+
+class Toolset:
+    """Schemas + execution for one bound embodiment. Built via ``build_toolset``."""
+
+    def __init__(
+        self,
+        *,
+        absolute: bool,
+        labels: tuple[str, ...],
+        state_key: str | None,
+        control_hz: float | None,
+        bounds_text: str,
+    ):
+        self._absolute = absolute
+        self._labels = labels
+        self._index_by_label = {label: i for i, label in enumerate(labels)}
+        self._state_key = state_key
+        self._hz = control_hz
+        self._move_tool = "move_joints" if absolute else "move_by"
+        self._bounds_text = bounds_text
+
+    # -- schemas ---------------------------------------------------------------
+
+    def schemas(self) -> list[dict[str, Any]]:
+        """OpenAI-format tool definitions for this embodiment."""
+        if self._absolute:
+            move_description = (
+                "Move to absolute joint/dimension targets, smoothly interpolated "
+                "from the current pose over duration_s. Unnamed dimensions hold "
+                "their current value. " + self._bounds_text
+            )
+            values_key = "targets"
+        else:
+            move_description = (
+                "Move BY the given displacement per dimension, split evenly over "
+                "duration_s. Unnamed dimensions do not move. " + self._bounds_text
+            )
+            values_key = "deltas"
+        move = {
+            "type": "function",
+            "function": {
+                "name": self._move_tool,
+                "description": move_description,
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        values_key: {
+                            "type": "object",
+                            "description": (
+                                "Map of dimension name to value. Valid names: "
+                                + ", ".join(self._labels)
+                            ),
+                        },
+                        "duration_s": {
+                            "type": "number",
+                            "description": f"Motion duration in seconds (0 < d <= {_MAX_DURATION_S})",
+                        },
+                    },
+                    "required": [values_key, "duration_s"],
+                },
+            },
+        }
+        done = {
+            "type": "function",
+            "function": {
+                "name": "done",
+                "description": "Declare the task finished. The trial ends; a scorer judges success.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {"summary": {"type": "string"}},
+                    "required": ["summary"],
+                },
+            },
+        }
+        give_up = {
+            "type": "function",
+            "function": {
+                "name": "give_up",
+                "description": "Stop trying; the task cannot be completed. The trial ends.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {"reason": {"type": "string"}},
+                    "required": ["reason"],
+                },
+            },
+        }
+        return [move, done, give_up]
+
+    # -- execution ---------------------------------------------------------------
+
+    def execute(self, call: Any, observation: Observation) -> ToolResult:
+        """Turn one tool call into an ActionChunk, or an error string for the LLM."""
+        try:
+            arguments = json.loads(call.arguments)
+        except (TypeError, ValueError):
+            return ToolResult(error=f"arguments for {call.name} are not valid JSON")
+        if not isinstance(arguments, dict):
+            return ToolResult(error=f"arguments for {call.name} must be a JSON object")
+        if call.name in ("done", "give_up"):
+            return self._stop(call.name, arguments, observation)
+        if call.name != self._move_tool:
+            return ToolResult(
+                error=f"unknown tool {call.name!r}; available: {self._move_tool}, done, give_up"
+            )
+        return self._move(arguments, observation)
+
+    def _current_state(self, observation: Observation) -> npt.NDArray[np.float64]:
+        if self._state_key is None:
+            return np.zeros(len(self._labels))
+        return np.asarray(observation.state[self._state_key], dtype=np.float64)
+
+    def _stop(self, name: str, arguments: dict[str, Any], observation: Observation) -> ToolResult:
+        # Hold still per control mode: repeat the pose (absolute) or move by
+        # nothing (displacement), flagged for rollout's policy-stop channel.
+        data = self._current_state(observation) if self._absolute else np.zeros(len(self._labels))
+        detail = str(arguments.get("summary") or arguments.get("reason") or "")
+        action = Action(
+            data=data,
+            meta={"request_stop": True, "stop_reason": name, "stop_detail": detail},
+        )
+        return ToolResult(
+            chunk=ActionChunk(actions=[action], control_hz=self._hz),
+            note=f"{name}: {detail}",
+        )
+
+    def _move(self, arguments: dict[str, Any], observation: Observation) -> ToolResult:
+        values_key = "targets" if self._absolute else "deltas"
+        values = arguments.get(values_key)
+        duration = arguments.get("duration_s")
+        if not isinstance(values, dict) or not values:
+            return ToolResult(error=f"{values_key} must be a non-empty object of name: value")
+        if not isinstance(duration, (int, float)) or isinstance(duration, bool):
+            return ToolResult(error="duration_s must be a number")
+        if not 0 < float(duration) <= _MAX_DURATION_S:
+            return ToolResult(
+                error=f"duration_s must be in (0, {_MAX_DURATION_S}] seconds, got {duration}"
+            )
+
+        vector = np.zeros(len(self._labels))
+        for label, raw in values.items():
+            index = self._index_by_label.get(str(label))
+            if index is None:
+                return ToolResult(
+                    error=f"unknown dimension {label!r}; valid names: {', '.join(self._labels)}"
+                )
+            if isinstance(raw, bool) or not isinstance(raw, (int, float)) or not np.isfinite(raw):
+                return ToolResult(error=f"value for {label!r} must be a finite number, got {raw!r}")
+            vector[index] = float(raw)
+
+        hz = self._hz if self._hz is not None else _FALLBACK_HZ
+        steps = max(1, round(float(duration) * hz))
+        if self._absolute:
+            current = self._current_state(observation)
+            target = current.copy()
+            for label in values:
+                target[self._index_by_label[str(label)]] = vector[self._index_by_label[str(label)]]
+            fractions = np.linspace(1.0 / steps, 1.0, steps)
+            actions = [Action(data=current + (target - current) * f) for f in fractions]
+        else:
+            per_step = vector / steps
+            actions = [Action(data=per_step.copy()) for _ in range(steps)]
+        return ToolResult(
+            chunk=ActionChunk(actions=actions, control_hz=self._hz),
+            note=f"executing {self._move_tool} over {steps} steps ({duration}s)",
+        )
+
+
+def build_toolset(
+    action_space: Box, observation_space: ObservationSpace, control_hz: float | None
+) -> Toolset:
+    """Validate a (action space, observation space) pairing and build its tools.
+
+    Raises [`ToolsetError`][inspect_robots_agent._tools.ToolsetError] with a
+    clear message for configurations the motion layer cannot drive — at bind
+    time, never mid-trial.
+    """
+    semantics = action_space.semantics
+    if semantics is None:
+        raise ToolsetError(
+            "the embodiment's action space declares no semantics; the agent cannot "
+            "tell absolute targets from displacements"
+        )
+    mode = semantics.control_mode
+    if mode in _POSE_MODES and semantics.rotation_repr not in _SAFE_ROT:
+        raise ToolsetError(
+            f"rotation_repr {semantics.rotation_repr!r} cannot be driven per-dimension; "
+            f"only {sorted(_SAFE_ROT)} are supported"
+        )
+    if mode not in _ABSOLUTE_MODES | _DISPLACEMENT_MODES:
+        raise ToolsetError(f"control_mode {mode!r} is not supported by the agent policy yet")
+
+    absolute = mode in _ABSOLUTE_MODES
+    dim = action_space.dim
+    state_key: str | None = None
+    if absolute:
+        spec = observation_space.state
+        if spec is None:
+            raise ToolsetError(
+                "absolute-target control needs a StateSpec on the embodiment's "
+                "observation space to locate the proprioceptive reference"
+            )
+        matching = [f.key for f in spec.fields if f.shape == (dim,)]
+        if len(matching) != 1:
+            raise ToolsetError(
+                f"absolute-target control needs exactly one state field with shape "
+                f"({dim},); found {matching or 'none'}"
+            )
+        state_key = matching[0]
+
+    labels = semantics.dim_labels or tuple(str(i) for i in range(dim))
+    low, high = action_space.low, action_space.high
+    if low is not None and high is not None:
+        pairs = ", ".join(
+            f"{label}: [{lo:.4g}, {hi:.4g}]"
+            for label, lo, hi in zip(labels, low.tolist(), high.tolist())
+        )
+        bounds_text = f"Per-dimension bounds: {pairs}."
+    else:
+        bounds_text = "The action space declares no bounds; move conservatively."
+
+    return Toolset(
+        absolute=absolute,
+        labels=labels,
+        state_key=state_key,
+        control_hz=control_hz,
+        bounds_text=bounds_text,
+    )

inspect_robots_agent/policy.py

@@ -0,0 +1,211 @@
+"""LLMAgentPolicy — a frontier LLM as a first-class Inspect Robots policy.
+
+The conversation loop lives inside ``act()``: observation in (labeled state
+text + camera frames), one validated tool call out, synthesized into an
+open-loop ``ActionChunk`` by the motion layer. The LLM never sees raw
+actuation, and every emitted action still passes the rollout's approver
+chain — this module contains no safety-critical code path of its own
+(plan 0008 §4b).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+import numpy as np
+
+from inspect_robots.embodiment import EmbodimentInfo
+from inspect_robots.policy import PolicyBase, PolicyConfig, PolicyInfo
+from inspect_robots.scene import Scene
+from inspect_robots.spaces import Box
+from inspect_robots.types import ActionChunk, Observation
+from inspect_robots_agent._llm import ENV_MODEL, ChatClient, ToolCall, resolve_provider
+from inspect_robots_agent._png import png_data_url
+from inspect_robots_agent._tools import Toolset, build_toolset
+
+_MAX_CONSECUTIVE_FAILURES = 3
+
+_SYSTEM_TEMPLATE = """You are controlling a real robot embodiment named {name!r} \
+through tool calls. Each observation message gives you the current \
+proprioceptive state and camera images. Work toward the user's goal in \
+small, deliberate motions; re-check the observation after every motion. \
+Safety approvers clamp out-of-bounds and too-fast actions below you. \
+Respond with exactly one tool call per turn. When the goal is achieved call \
+done; if it cannot be achieved call give_up. You have a budget of \
+{budget} LLM calls for the whole trial."""
+
+
+@dataclass(frozen=True)
+class AgentPolicyConfig(PolicyConfig):
+    """Inference-time configuration recorded in the eval log.
+
+    Extends the core ``PolicyConfig``; ``eval()`` serializes configs with
+    ``dataclasses.asdict``, so these fields land in ``EvalSpec.policy_config``
+    for free.
+    """
+
+    model: str | None = None
+    base_url: str | None = None
+    api_key_env: str | None = None
+    max_llm_calls: int = 50
+
+
+class LLMAgentPolicy(PolicyBase):
+    """Drives whatever embodiment it is bound to via LLM tool calls.
+
+    Embodiment-adaptive: ``bind()`` (called by ``eval()`` before the
+    compatibility check) adopts the embodiment's spaces and builds the tool
+    surface from them. Conversation state is per-trial (``reset``).
+    """
+
+    def __init__(
+        self,
+        model: str | None = None,
+        base_url: str | None = None,
+        api_key_env: str | None = None,
+        max_llm_calls: int = 50,
+        temperature: float | None = None,
+        transport: httpx.BaseTransport | None = None,
+        env: dict[str, str] | None = None,
+    ):
+        environ = dict(os.environ) if env is None else env
+        provider = resolve_provider(
+            model=model or environ.get(ENV_MODEL),
+            base_url=base_url,
+            api_key_env=api_key_env,
+            env=environ,
+        )
+        if max_llm_calls < 1:
+            raise ValueError("max_llm_calls must be >= 1")
+        self._client = ChatClient(provider, transport=transport)
+        self._max_llm_calls = max_llm_calls
+        self._temperature = temperature
+        self.config = AgentPolicyConfig(
+            temperature=temperature,
+            model=provider.model,
+            base_url=provider.base_url,
+            api_key_env=api_key_env,
+            max_llm_calls=max_llm_calls,
+        )
+        # Placeholder until bind(); eval() always binds before compat/rollout.
+        self.info = PolicyInfo(name="agent", action_space=Box(shape=(1,)))
+        self._toolset: Toolset | None = None
+        self._embodiment_name = "(unbound)"
+        self._messages: list[dict[str, Any]] = []
+        self._calls_used = 0
+
+    # -- lifecycle ---------------------------------------------------------------
+
+    def bind(self, embodiment_info: EmbodimentInfo) -> None:
+        """Adopt the embodiment's spaces and build the tool surface from them."""
+        self._toolset = build_toolset(
+            embodiment_info.action_space,
+            embodiment_info.observation_space,
+            embodiment_info.control_hz,
+        )
+        self._embodiment_name = embodiment_info.name
+        self.info = PolicyInfo(
+            name="agent",
+            action_space=embodiment_info.action_space,
+            observation_space=embodiment_info.observation_space,
+            control_hz=embodiment_info.control_hz,
+        )
+
+    def reset(self, scene: Scene) -> None:
+        self._messages = [
+            {
+                "role": "system",
+                "content": _SYSTEM_TEMPLATE.format(
+                    name=self._embodiment_name, budget=self._max_llm_calls
+                ),
+            },
+            {"role": "user", "content": f"Goal: {scene.instruction}"},
+        ]
+        self._calls_used = 0
+
+    # -- the loop ------------------------------------------------------------------
+
+    def act(self, observation: Observation) -> ActionChunk:
+        toolset = self._toolset
+        if toolset is None:
+            raise RuntimeError(
+                "LLMAgentPolicy.act() before bind(); run it through eval() or call "
+                "policy.bind(embodiment.info) first"
+            )
+        self._messages.append({"role": "user", "content": _observation_content(observation)})
+        failures = 0
+        while True:
+            if self._calls_used >= self._max_llm_calls:
+                return self._forced_give_up(toolset, observation, "LLM call budget exhausted")
+            message = self._client.complete(
+                self._messages, toolset.schemas(), temperature=self._temperature
+            )
+            self._calls_used += 1
+            self._messages.append(message.raw())
+
+            if not message.tool_calls:
+                failures += 1
+                if failures >= _MAX_CONSECUTIVE_FAILURES:
+                    raise RuntimeError(f"LLM produced no tool call in {failures} consecutive turns")
+                self._messages.append(
+                    {"role": "user", "content": "Respond with exactly one tool call."}
+                )
+                continue
+
+            call, *extras = message.tool_calls
+            for extra in extras:
+                # Every tool_call id needs an answer on the wire; only the
+                # first call per turn is executed.
+                self._messages.append(
+                    {
+                        "role": "tool",
+                        "tool_call_id": extra.id,
+                        "content": "ignored: one tool call per turn",
+                    }
+                )
+            result = toolset.execute(call, observation)
+            self._messages.append(
+                {"role": "tool", "tool_call_id": call.id, "content": result.error or result.note}
+            )
+            if result.error:
+                failures += 1
+                if failures >= _MAX_CONSECUTIVE_FAILURES:
+                    raise RuntimeError(f"LLM tool calls kept failing; last error: {result.error}")
+                continue
+            assert result.chunk is not None  # execute() sets exactly one of chunk/error
+            return result.chunk
+
+    def _forced_give_up(self, toolset: Toolset, observation: Observation, why: str) -> ActionChunk:
+        synthetic = ToolCall(id="budget", name="give_up", arguments=json.dumps({"reason": why}))
+        result = toolset.execute(synthetic, observation)
+        assert result.chunk is not None
+        return result.chunk
+
+
+def _observation_content(observation: Observation) -> list[dict[str, Any]]:
+    """State as readable text plus camera frames as inline PNG data URLs."""
+    lines = ["Current observation."]
+    if observation.instruction:
+        lines.append(f"Instruction: {observation.instruction}")
+    for key, value in observation.state.items():
+        rounded = np.round(np.asarray(value, dtype=np.float64), 4).tolist()
+        lines.append(f"state[{key}]: {rounded}")
+    parts: list[dict[str, Any]] = [{"type": "text", "text": "\n".join(lines)}]
+    for name, image in observation.images.items():
+        parts.append({"type": "text", "text": f"camera {name!r}:"})
+        parts.append({"type": "image_url", "image_url": {"url": png_data_url(image)}})
+    return parts
+
+
+def agent_policy(**kwargs: Any) -> LLMAgentPolicy:
+    """Factory the Inspect Robots registry calls (entry point ``agent``).
+
+    Accepts the same keyword arguments as
+    [`LLMAgentPolicy`][inspect_robots_agent.policy.LLMAgentPolicy]; the CLI
+    forwards ``-P key=value`` pairs here.
+    """
+    return LLMAgentPolicy(**kwargs)

inspect_robots_agent-0.1.0.dist-info/METADATA

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: inspect-robots-agent
+Version: 0.1.0
+Summary: LLM agent policy for Inspect Robots: frontier LLMs (Claude, GPT, anything OpenAI-compatible) drive any registered embodiment through tool calls.
+Project-URL: Homepage, https://github.com/robocurve/inspect-robots/tree/main/plugins/inspect-robots-agent
+Project-URL: Repository, https://github.com/robocurve/inspect-robots
+Author: Inspect Robots contributors
+License-Expression: MIT
+Keywords: agent,evaluation,inspect_robots,llm,robotics,vla
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: inspect-robots>=0.4
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# inspect-robots-agent
+
+LLM agent policy for [Inspect Robots](https://github.com/robocurve/inspect-robots):
+frontier LLMs (Claude, GPT, anything behind an OpenAI-compatible API) drive any
+registered embodiment through tool calls, as a first-class `Policy` named
+`agent`. The same policy runs ad-hoc instructions and scores on registered
+tasks next to fine-tuned VLAs.
+
+## Install
+
+```bash
+pip install inspect-robots inspect-robots-agent
+```
+
+## Quickstart (no hardware)
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+
+inspect-robots "pick up the cube" --policy agent \
+    -P model=anthropic/claude-fable-5 --embodiment cubepick
+```
+
+Model strings are OpenRouter-style `provider/model`, resolved from
+`-P model=...` or `$INSPECT_ROBOTS_MODEL`. API keys come from the environment:
+
+1. `-P base_url=...` (with `-P api_key_env=NAME`): any OpenAI-compatible endpoint
+2. `anthropic/*` model with `ANTHROPIC_API_KEY`: the Anthropic compat endpoint
+3. `openai/*` model with `OPENAI_API_KEY`: OpenAI
+4. `OPENROUTER_API_KEY`: OpenRouter, any model string
+
+## How it works
+
+Each LLM tool call becomes one smooth, open-loop action chunk: named partial
+joint targets are interpolated at the embodiment's control rate
+(`move_joints`), displacements are split across steps (`move_by`), and
+`done`/`give_up` end the trial through the core's policy-stop channel. Every
+action still passes the CLI's default safety approvers (bounds clamp plus
+per-step delta limit); the plugin contains no safety-critical code path of
+its own.
+
+> **Warning:**
+> Guardrails are on by default at the CLI. **Never pass `--disable-guardrails`
+> on real hardware** unless you fully trust the policy and the rig.
+
+Configuration knobs (all `-P key=value`): `model`, `base_url`, `api_key_env`,
+`max_llm_calls`, `temperature`.

inspect_robots_agent-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+inspect_robots_agent/__init__.py,sha256=VXmY2Xr1USMOve2eqp3EhvOwV1ObhedCW_COezgg-oo,1021
+inspect_robots_agent/_llm.py,sha256=Vm7yWbrCtJ9uQlGFiHQ-d6FfyuaNvBPJ1_VyiaVIJYM,6741
+inspect_robots_agent/_png.py,sha256=ESKxe8iRc982L8Jv_ScZvT5iWNLwQEjE6Sp1sV6_gSs,1648
+inspect_robots_agent/_tools.py,sha256=uoyuF_UgmWfsQid3IQY_rjYSd5BC-psLm6NOEruJ_sM,11555
+inspect_robots_agent/policy.py,sha256=oFUAF4jjPFUd_C0t0-cMwRgN-7b-TRS-DJ19BkcoaWU,8629
+inspect_robots_agent/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+inspect_robots_agent-0.1.0.dist-info/METADATA,sha256=UsVAfnd2g670v9L78c5D89PjQL_QH8QB9jehvRlyhJ4,2934
+inspect_robots_agent-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+inspect_robots_agent-0.1.0.dist-info/entry_points.txt,sha256=o8w6RAsKhdQlvxFprv2PF3tJeLcFg2kOuEMd2rPBp4Y,75
+inspect_robots_agent-0.1.0.dist-info/RECORD,,

inspect_robots_agent-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

inspect_robots_agent-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[inspect_robots.policies]
+agent = inspect_robots_agent.policy:agent_policy