Add verifiers integration bridge

Author: Kioja

docs/docs.json

@@ -75,7 +75,8 @@
         "group": "Integrations",
         "pages": [
           "integrations/langgraph-integration",
-          "integrations/openenv-integration"
+          "integrations/openenv-integration",
+          "integrations/verifiers-integration"
         ]
       },
       {

docs/integrations/verifiers-integration.mdx

@@ -0,0 +1,98 @@
+---
+title: "Verifiers"
+description: "Run Prime Intellect verifiers environments from ART training loops"
+---
+
+# Verifiers Integration
+
+[verifiers](https://github.com/PrimeIntellect-ai/verifiers) provides reusable RL
+environments for model evaluation and training. ART can consume those rollouts
+through `art.verifiers`, which keeps verifiers as an optional dependency and
+converts rollout outputs into ART trajectories.
+
+## Install
+
+```bash
+uv pip install -U openpipe-art verifiers
+```
+
+## Run a verifiers environment in ART
+
+Use `rollout_with_verifiers_environment` inside your ART rollout function. It
+passes ART's managed OpenAI-compatible client to the verifiers environment and
+returns an `art.Trajectory`.
+
+```python
+import art
+from art.verifiers import rollout_with_verifiers_environment
+import verifiers as vf
+
+
+async def rollout(
+    model: art.TrainableModel,
+    env: vf.Environment,
+    input: vf.RolloutInput,
+) -> art.Trajectory:
+    return await rollout_with_verifiers_environment(
+        env,
+        model,
+        input,
+        sampling_args={"n": 1, "temperature": 1.0},
+    )
+```
+
+For grouped rollouts, use `trajectory_group_with_verifiers_environment`:
+
+```python
+from art.verifiers import trajectory_group_with_verifiers_environment
+
+group = await trajectory_group_with_verifiers_environment(
+    env,
+    model,
+    group_inputs,
+    sampling_args={"n": 1, "temperature": 1.0},
+)
+```
+
+## Convert saved rollouts
+
+If you already have verifiers outputs, convert them without rerunning the
+environment:
+
+```python
+from art.verifiers import trajectory_from_verifiers_rollout
+
+trajectory = trajectory_from_verifiers_rollout(output)
+```
+
+For the richest transcript, include the verifiers trajectory column when
+generating outputs:
+
+```python
+output = await env.run_rollout(
+    input=input,
+    client=client,
+    model=model_name,
+    sampling_args={"n": 1},
+    state_columns=["trajectory"],
+)
+```
+
+The reverse conversion is also available for tooling that expects a
+verifiers-compatible output shape:
+
+```python
+from art.verifiers import rollout_output_from_trajectory
+
+output = rollout_output_from_trajectory(trajectory)
+```
+
+## Notes
+
+- `art.verifiers` does not import verifiers until you call a function that
+  runs an environment.
+- Multi-turn verifiers trajectories are reconstructed by appending only the
+  new prompt suffix for each step, then that step's completion.
+- ART trajectories created from serialized verifiers outputs can train with
+  `allow_training_without_logprobs=True` because serialized assistant messages
+  do not carry OpenAI logprobs.

src/art/test/test_verifiers_bridge.py

@@ -0,0 +1,263 @@
+import sys
+import types
+
+import art
+from art.verifiers import (
+    rollout_output_from_trajectory,
+    rollout_outputs_from_trajectory_group,
+    rollout_with_verifiers_environment,
+    trajectory_from_verifiers_rollout,
+    trajectory_group_from_verifiers_outputs,
+    trajectory_group_with_verifiers_environment,
+)
+
+
+def test_trajectory_from_verifiers_rollout_reconstructs_multiturn_steps():
+    output = {
+        "example_id": 7,
+        "prompt": [{"role": "user", "content": "Find the invoice"}],
+        "reward": 1.0,
+        "metrics": {"accuracy": 1.0, "notes": "ignored"},
+        "is_completed": True,
+        "is_truncated": False,
+        "stop_condition": "answer_ready",
+        "tool_defs": [
+            {
+                "name": "search",
+                "description": "Search mail",
+                "parameters": {"type": "object", "properties": {}},
+            }
+        ],
+        "trajectory": [
+            {
+                "prompt": [{"role": "user", "content": "Find the invoice"}],
+                "completion": [{"role": "assistant", "content": "Searching"}],
+            },
+            {
+                "prompt": [
+                    {"role": "user", "content": "Find the invoice"},
+                    {"role": "assistant", "content": "Searching"},
+                    {"role": "tool", "tool_call_id": "t1", "content": "Invoice #42"},
+                ],
+                "completion": [{"role": "assistant", "content": "Invoice #42"}],
+            },
+        ],
+    }
+
+    trajectory = trajectory_from_verifiers_rollout(output)
+
+    assert trajectory.reward == 1.0
+    assert trajectory.metrics["accuracy"] == 1.0
+    assert trajectory.metadata["verifiers_example_id"] == 7
+    assert trajectory.metadata["verifiers_stop_condition"] == "answer_ready"
+    assert trajectory.messages_and_choices == [
+        {"role": "user", "content": "Find the invoice"},
+        {"role": "assistant", "content": "Searching"},
+        {"role": "tool", "tool_call_id": "t1", "content": "Invoice #42"},
+        {"role": "assistant", "content": "Invoice #42"},
+    ]
+    assert trajectory.tools == [
+        {
+            "type": "function",
+            "function": {
+                "name": "search",
+                "description": "Search mail",
+                "parameters": {"type": "object", "properties": {}},
+            },
+        }
+    ]
+
+
+def test_trajectory_from_verifiers_rollout_falls_back_to_prompt_completion():
+    output = {
+        "prompt": [{"role": "user", "content": "2 + 2?"}],
+        "completion": [{"role": "assistant", "content": "4"}],
+        "reward": 1,
+    }
+
+    trajectory = trajectory_from_verifiers_rollout(output)
+
+    assert trajectory.messages_and_choices == [
+        {"role": "user", "content": "2 + 2?"},
+        {"role": "assistant", "content": "4"},
+    ]
+
+
+def test_rollout_output_from_trajectory_splits_prompt_and_completion():
+    trajectory = art.Trajectory(
+        messages_and_choices=[
+            {"role": "system", "content": "Be concise"},
+            {"role": "user", "content": "2 + 2?"},
+            {"role": "assistant", "content": "4"},
+        ],
+        reward=0.75,
+        metrics={"accuracy": 1.0},
+        metadata={"trajectory_id": "abc"},
+        tools=[
+            {
+                "type": "function",
+                "function": {
+                    "name": "calculator",
+                    "description": "Calculate",
+                    "parameters": {"type": "object", "properties": {}},
+                },
+            }
+        ],
+    )
+
+    output = rollout_output_from_trajectory(trajectory, example_id=3)
+
+    assert output["example_id"] == 3
+    assert output["prompt"] == [
+        {"role": "system", "content": "Be concise"},
+        {"role": "user", "content": "2 + 2?"},
+    ]
+    assert output["completion"] == [{"role": "assistant", "content": "4"}]
+    assert output["reward"] == 0.75
+    assert output["metrics"] == {"accuracy": 1.0}
+    assert output["tool_defs"] == [
+        {
+            "name": "calculator",
+            "description": "Calculate",
+            "parameters": {"type": "object", "properties": {}},
+        }
+    ]
+    assert output["trajectory"][0]["trajectory_id"] == "abc"
+
+
+def test_trajectory_group_from_verifiers_outputs():
+    group = trajectory_group_from_verifiers_outputs(
+        [
+            {"prompt": "first", "completion": [{"role": "assistant", "content": "a"}]},
+            {"prompt": "second", "completion": [{"role": "assistant", "content": "b"}]},
+        ]
+    )
+
+    assert len(group) == 2
+    assert group.trajectories[0].messages_and_choices[0] == {
+        "role": "user",
+        "content": "first",
+    }
+
+
+def test_rollout_outputs_from_trajectory_group_assigns_example_ids():
+    group = art.TrajectoryGroup(
+        [
+            art.Trajectory(
+                messages_and_choices=[
+                    {"role": "user", "content": "first"},
+                    {"role": "assistant", "content": "a"},
+                ],
+                reward=1.0,
+            ),
+            art.Trajectory(
+                messages_and_choices=[
+                    {"role": "user", "content": "second"},
+                    {"role": "assistant", "content": "b"},
+                ],
+                reward=0.5,
+            ),
+        ]
+    )
+
+    outputs = rollout_outputs_from_trajectory_group(group, first_example_id=10)
+
+    assert [output["example_id"] for output in outputs] == [10, 11]
+    assert [output["reward"] for output in outputs] == [1.0, 0.5]
+
+
+async def test_rollout_with_verifiers_environment_uses_art_model_client(monkeypatch):
+    _install_fake_verifiers_client(monkeypatch)
+    env = _FakeVerifiersEnv()
+    model = _FakeArtModel()
+
+    trajectory = await rollout_with_verifiers_environment(
+        env,
+        model,
+        {"prompt": [{"role": "user", "content": "hi"}], "example_id": 1},
+        sampling_args={"temperature": 0.2},
+        state_columns=("trajectory", "custom"),
+    )
+
+    assert trajectory.reward == 1.0
+    assert trajectory.messages_and_choices[-1] == {
+        "role": "assistant",
+        "content": "done",
+    }
+    assert env.last_rollout_call["client"].raw_client == "art-openai-client"
+    assert env.last_rollout_call["model"] == "art-model"
+    assert env.last_rollout_call["sampling_args"] == {"temperature": 0.2}
+    assert env.last_rollout_call["state_columns"] == ["trajectory", "custom"]
+
+
+async def test_trajectory_group_with_verifiers_environment(monkeypatch):
+    _install_fake_verifiers_client(monkeypatch)
+    env = _FakeVerifiersEnv()
+    model = _FakeArtModel()
+
+    group = await trajectory_group_with_verifiers_environment(
+        env,
+        model,
+        [{"prompt": "a"}, {"prompt": "b"}],
+    )
+
+    assert len(group) == 2
+    assert env.last_group_call["client"].raw_client == "art-openai-client"
+    assert env.last_group_call["model"] == "art-model"
+    assert group.trajectories[0].messages_and_choices[-1] == {
+        "role": "assistant",
+        "content": "group done",
+    }
+
+
+class _FakeArtModel:
+    def openai_client(self):
+        return "art-openai-client"
+
+    def get_inference_name(self):
+        return "art-model"
+
+
+class _FakeOpenAIChatCompletionsClient:
+    def __init__(self, raw_client):
+        self.raw_client = raw_client
+
+
+class _FakeVerifiersEnv:
+    def __init__(self):
+        self.last_rollout_call = None
+        self.last_group_call = None
+
+    async def run_rollout(self, **kwargs):
+        self.last_rollout_call = kwargs
+        return {
+            "prompt": kwargs["input"]["prompt"],
+            "completion": [{"role": "assistant", "content": "done"}],
+            "reward": 1.0,
+        }
+
+    async def run_group(self, **kwargs):
+        self.last_group_call = kwargs
+        return [
+            {
+                "prompt": input_value["prompt"],
+                "completion": [{"role": "assistant", "content": "group done"}],
+                "reward": 1.0,
+            }
+            for input_value in kwargs["group_inputs"]
+        ]
+
+
+def _install_fake_verifiers_client(monkeypatch):
+    verifiers_module = types.ModuleType("verifiers")
+    clients_module = types.ModuleType("verifiers.clients")
+    client_module = types.ModuleType("verifiers.clients.openai_chat_completions_client")
+    client_module.OpenAIChatCompletionsClient = _FakeOpenAIChatCompletionsClient
+
+    monkeypatch.setitem(sys.modules, "verifiers", verifiers_module)
+    monkeypatch.setitem(sys.modules, "verifiers.clients", clients_module)
+    monkeypatch.setitem(
+        sys.modules,
+        "verifiers.clients.openai_chat_completions_client",
+        client_module,
+    )