inspect-robots-agent 0.1.0__tar.gz

inspect_robots_agent-0.1.0/.gitignore

@@ -0,0 +1,221 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer,
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# uv.lock is committed: CI installs with `uv sync --locked` for reproducible
+# builds. Run `uv lock` after changing dependencies in pyproject.toml.

inspect_robots_agent-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,47 @@
+# 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/pyproject.toml

@@ -0,0 +1,90 @@
+[build-system]
+requires = ["hatchling>=1.18", "hatch-fancy-pypi-readme>=24.1"]
+build-backend = "hatchling.build"
+
+[project]
+name = "inspect-robots-agent"
+version = "0.1.0"
+description = "LLM agent policy for Inspect Robots: frontier LLMs (Claude, GPT, anything OpenAI-compatible) drive any registered embodiment through tool calls."
+dynamic = ["readme"]
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Inspect Robots contributors" }]
+keywords = ["robotics", "llm", "agent", "vla", "inspect_robots", "evaluation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+# NOTE: no provider SDKs. The adapter speaks the OpenAI chat-completions wire
+# format over one httpx client, which covers OpenRouter, OpenAI, local
+# vLLM/Ollama, and Anthropic's OpenAI-compat endpoint (plan 0008 §4a) — the
+# same "speak the protocol, don't import the package" doctrine as the
+# xpolicylab plugin.
+dependencies = [
+    "inspect-robots>=0.4",
+    "numpy>=1.24",
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-cov>=5.0", "mypy>=1.11", "ruff>=0.6"]
+
+# Entry-point discovery: an installed inspect-robots-agent appears in
+# `inspect-robots list policies` without being imported first. The registry
+# calls this factory by the name `agent`.
+[project.entry-points."inspect_robots.policies"]
+agent = "inspect_robots_agent.policy:agent_policy"
+
+[project.urls]
+Homepage = "https://github.com/robocurve/inspect-robots/tree/main/plugins/inspect-robots-agent"
+Repository = "https://github.com/robocurve/inspect-robots"
+
+# In the Inspect Robots monorepo this resolves the `inspect_robots` dependency
+# to the in-repo core package instead of PyPI. Harmless in a standalone
+# checkout (uv ignores a workspace source when there is no workspace root).
+[tool.uv.sources]
+inspect-robots = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/inspect_robots_agent"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/inspect_robots_agent", "tests", "README.md"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.mypy]
+strict = true
+
+# PyPI readme: identical to README.md except GitHub-only alert syntax
+# (e.g. `> [!NOTE]`) is rewritten to bold blockquotes, which PyPI renders.
+[tool.hatch.metadata.hooks.fancy-pypi-readme]
+content-type = "text/markdown"
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.fragments]]
+path = "README.md"
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.substitutions]]
+pattern = '(?m)^> \[!NOTE\][ \t]*$'
+replacement = '> **Note:**'
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.substitutions]]
+pattern = '(?m)^> \[!TIP\][ \t]*$'
+replacement = '> **Tip:**'
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.substitutions]]
+pattern = '(?m)^> \[!IMPORTANT\][ \t]*$'
+replacement = '> **Important:**'
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.substitutions]]
+pattern = '(?m)^> \[!WARNING\][ \t]*$'
+replacement = '> **Warning:**'
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.substitutions]]
+pattern = '(?m)^> \[!CAUTION\][ \t]*$'
+replacement = '> **Caution:**'

inspect_robots_agent-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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")