[feature] Import external envs (ors, verifiers) (#726)

* feat: import external environments

* feat: add import integration demo

* fix: address import wrapper review feedback

* fix: satisfy ci formatting and tests

* fix: address import review comments

* fix: remove import demo example

* fix: extract importer source templates

* fix: satisfy lint formatting

* fix: add imported environment example

* fix: add qed math docs to toctree

Author: burtenshaw

README.md

@@ -268,6 +268,7 @@ See example scripts in `examples/` directory.
 The OpenEnv CLI provides commands to manage environments:
 
 - **`openenv init <env_name>`** - Initialize a new environment from template
+- **`openenv import <source> --name <env_name> --output-dir <dir>`** - Wrap a supported third-party source environment, including ORS/OpenReward and Verifiers, as OpenEnv
 - **`openenv push [--repo-id <repo>] [--private]`** - Deploy environment to Hugging Face Spaces
 - **`openenv serve`** - Serve an environment locally with optional auto-reload
 - **`openenv build`** - Build the Docker image for an environment
@@ -280,6 +281,9 @@ The OpenEnv CLI provides commands to manage environments:
 # Create a new environment
 openenv init my_game_env
 
+# Or import an ORS/OpenReward or Verifiers source environment
+openenv import path/to/source --name my_game_env --output-dir .
+
 # Deploy to Hugging Face (will prompt for login if needed)
 cd my_game_env
 openenv push

docs/source/_toctree.yml

@@ -115,6 +115,8 @@
     title: Maze
   - local: environments/openapp
     title: OpenApp
+  - local: environments/qed_math
+    title: QED Math
   - local: environments/reasoning_gym
     title: Reasoning Gym
   - local: environments/tbench2

docs/source/getting_started/environment-builder.md

@@ -27,6 +27,7 @@ Already familiar with OpenEnv? Here's the 8-step process at a glance:
 | Command | Description |
 |---------|-------------|
 | `openenv init NAME` | Scaffold new environment |
+| `openenv import SOURCE --name NAME --output-dir DIR` | Wrap a supported third-party environment source tree |
 | `uv run --project . server` | Start local dev server |
 | `openenv build` | Build Docker image |
 | `openenv validate --verbose` | Validate environment structure |
@@ -96,6 +97,14 @@ my_env/
 
 Python classes are generated for the action, observation, environment, and client. For example, you will find `MyEnvironment`, `MyAction`, `MyObservation`, and `MyEnv` (client) in the `my_env` directory based on the name you provided. The environment uses the core `State` class from `openenv.core.env_server.types`.
 
+If you already have an ORS/OpenReward or Prime Intellect Verifiers environment
+source tree, use `openenv import SOURCE --name my_env --output-dir /Users/you/envs`
+instead. The importer detects the source type from the code, vendors the source
+under the generated package, and emits an OpenEnv wrapper with task/split and
+MCP-style tool actions. Non-secret data files in the source tree are included as
+package data, and portable dependencies declared in source `pyproject.toml` or
+`requirements.txt` files are added to the generated environment.
+
 ### 2. Define Models
 
 Edit `models.py` to describe your action and observation using Pydantic:

docs/source/reference/cli.md

@@ -6,6 +6,34 @@ The `openenv` CLI provides a set of commands for building, validating, and pushi
 
 [[autodoc]] openenv.cli.commands.init.init
 
+## `openenv import`
+
+Import a supported third-party source environment into a generated OpenEnv
+wrapper package. The command detects the source format from the directory
+contents, so ORS/OpenReward and Prime Intellect Verifiers sources do not
+require `--type` in the common case.
+
+The generated wrapper vendors the source tree into the package and includes
+vendored files as package data, so non-secret fixture/data files are available to
+the environment server at runtime. The importer carries portable dependencies
+from source `pyproject.toml` and `requirements.txt` files into the generated
+environment, skips VCS/cache/build directories and common secret file patterns
+such as `.env`, `secrets.yaml`, and private key files, and excludes compiled
+binary artifacts; review the generated `vendor/` directory before publishing a
+wrapper.
+
+```bash
+openenv import path/to/source --name my_env --output-dir ./envs
+openenv import path/to/source --name my_env --output-dir ./envs --env-class MyEnv
+```
+
+```{eval-rst}
+.. automodule:: openenv.cli.commands.import_env
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
 ## `openenv build`
 
 [[autodoc]] openenv.cli.commands.build.build

examples/imported_environment/README.md

@@ -0,0 +1,18 @@
+# Imported Environment Usage
+
+This example imports the tiny ORS/OpenReward-style source in `source/` and then
+uses the generated OpenEnv wrapper.
+
+```bash
+uv run python examples/imported_environment/use_imported_environment.py
+```
+
+To keep the generated wrapper for inspection:
+
+```bash
+uv run python examples/imported_environment/use_imported_environment.py --output-dir /tmp/openenv-import-demo
+```
+
+The script runs `openenv import`, imports the generated
+`ImportedOrsDemoEnvironment`, calls `reset()`, lists the generated MCP-style
+tools, and submits an answer with `CallToolAction`.

examples/imported_environment/source/ors/__init__.py

@@ -0,0 +1,51 @@
+class Model:
+    def __init__(self, **kwargs):
+        self.__dict__.update(kwargs)
+
+    def model_dump(self):
+        return dict(self.__dict__)
+
+
+class Split(Model):
+    pass
+
+
+class ToolSpec(Model):
+    pass
+
+
+class ListToolsOutput(Model):
+    pass
+
+
+class TextBlock(Model):
+    def __init__(self, text, detail=None, type="text"):
+        super().__init__(text=text, detail=detail, type=type)
+
+
+class ToolOutput(Model):
+    pass
+
+
+class RunToolSuccess:
+    ok = True
+
+    def __init__(self, output):
+        self.output = output
+
+
+class RunToolOutput:
+    def __init__(self, output):
+        self.root = RunToolSuccess(output)
+
+
+class Environment:
+    def __init__(self, task_spec=None, secrets=None):
+        self.task_spec = task_spec or {}
+        self.secrets = secrets or {}
+
+    def setup(self):
+        pass
+
+    def teardown(self):
+        pass

examples/imported_environment/source/toy_ors_env.py

@@ -0,0 +1,72 @@
+from ors import (
+    Environment,
+    ListToolsOutput,
+    RunToolOutput,
+    Split,
+    TextBlock,
+    ToolOutput,
+    ToolSpec,
+)
+
+
+class ToyMathEnvironment(Environment):
+    @classmethod
+    def list_splits(cls):
+        return [Split(name="train", type="train")]
+
+    @classmethod
+    def list_tasks(cls, split):
+        return [
+            {
+                "id": "addition-1",
+                "question": "What is 2 + 2?",
+                "answer": "4",
+            }
+        ]
+
+    @classmethod
+    def num_tasks(cls, split):
+        return len(cls.list_tasks(split))
+
+    @classmethod
+    def get_task(cls, split, index):
+        return cls.list_tasks(split)[index]
+
+    @classmethod
+    def get_task_range(cls, split, start=None, stop=None):
+        return cls.list_tasks(split)[slice(start, stop)]
+
+    @classmethod
+    def list_tools(cls):
+        return ListToolsOutput(
+            tools=[
+                ToolSpec(
+                    name="answer",
+                    description="Submit an answer for the math question",
+                    input_schema={
+                        "type": "object",
+                        "properties": {"value": {"type": "string"}},
+                        "required": ["value"],
+                    },
+                )
+            ]
+        )
+
+    def list_task_tools(self):
+        return ListToolsOutput(tools=[])
+
+    def get_prompt(self):
+        return [TextBlock(text=self.task_spec["question"])]
+
+    def _call_tool(self, name, input):
+        guess = str(input.get("value", "")).strip()
+        expected = self.task_spec["answer"]
+        correct = guess == expected
+        return RunToolOutput(
+            ToolOutput(
+                blocks=[TextBlock(text="correct" if correct else "incorrect")],
+                metadata={"expected": expected, "received": guess},
+                reward=1.0 if correct else 0.0,
+                finished=True,
+            )
+        )

examples/imported_environment/use_imported_environment.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""Import and use a tiny ORS/OpenReward-style environment."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from typing import Any
+
+from openenv.core.env_server.mcp_types import CallToolAction, ListToolsAction
+
+
+ENV_NAME = "imported_ors_demo"
+EXAMPLE_DIR = Path(__file__).resolve().parent
+
+
+def import_environment(source_dir: Path, output_dir: Path) -> Path:
+    """Run the OpenEnv importer and return the generated package directory."""
+    output_dir.mkdir(parents=True, exist_ok=True)
+    generated_dir = output_dir / ENV_NAME
+    if generated_dir.exists():
+        shutil.rmtree(generated_dir)
+
+    subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "openenv.cli",
+            "import",
+            str(source_dir),
+            "--name",
+            ENV_NAME,
+            "--output-dir",
+            str(output_dir),
+        ],
+        check=True,
+    )
+    return generated_dir
+
+
+def _clear_demo_modules() -> None:
+    for module_name in list(sys.modules):
+        if module_name == ENV_NAME or module_name.startswith(f"{ENV_NAME}."):
+            sys.modules.pop(module_name, None)
+        if module_name == "ors" or module_name.startswith("ors."):
+            sys.modules.pop(module_name, None)
+
+
+def run_imported_environment(output_dir: Path) -> dict[str, Any]:
+    """Use the generated OpenEnv wrapper directly."""
+    _clear_demo_modules()
+    sys.path.insert(0, str(output_dir))
+    try:
+        from imported_ors_demo.server.imported_ors_demo_environment import (  # type: ignore
+            ImportedOrsDemoEnvironment,
+        )
+
+        env = ImportedOrsDemoEnvironment()
+        reset_observation = env.reset(split="train", index=0)
+        tools_observation = env.step(ListToolsAction())
+        answer_observation = env.step(
+            CallToolAction(tool_name="answer", arguments={"value": "4"})
+        )
+
+        return {
+            "prompt": reset_observation.metadata["prompt"][0]["text"],
+            "tools": [tool.name for tool in tools_observation.tools],
+            "result": answer_observation.result["blocks"][0]["text"],
+            "reward": answer_observation.reward,
+            "done": answer_observation.done,
+        }
+    finally:
+        try:
+            sys.path.remove(str(output_dir))
+        except ValueError:
+            pass
+        _clear_demo_modules()
+
+
+def _print_summary(generated_dir: Path, summary: dict[str, Any]) -> None:
+    print(f"Generated environment: {generated_dir}")
+    print(f"Prompt: {summary['prompt']}")
+    print(f"Tools: {', '.join(summary['tools'])}")
+    print(f"Tool result: {summary['result']}")
+    print(f"Reward: {summary['reward']}")
+    print(f"Done: {summary['done']}")
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--output-dir",
+        type=Path,
+        help="Directory for the generated OpenEnv package. Defaults to a temp dir.",
+    )
+    args = parser.parse_args(argv)
+
+    source_dir = EXAMPLE_DIR / "source"
+    if args.output_dir is not None:
+        output_dir = args.output_dir.resolve()
+        generated_dir = import_environment(source_dir, output_dir)
+        summary = run_imported_environment(output_dir)
+        _print_summary(generated_dir, summary)
+        return
+
+    with TemporaryDirectory() as tmp:
+        output_dir = Path(tmp)
+        generated_dir = import_environment(source_dir, output_dir)
+        summary = run_imported_environment(output_dir)
+        _print_summary(generated_dir, summary)
+
+
+if __name__ == "__main__":
+    main()

pyproject.toml

@@ -65,6 +65,7 @@ include-package-data = true
 
 [tool.setuptools.package-data]
 "openenv.cli" = ["templates/**/*"]
+"openenv.cli.importers" = ["templates/**/*"]
 
 [tool.setuptools.exclude-package-data]
 "*" = ["*.pyc", "*.pyo", "__pycache__/*"]

src/openenv/cli/__main__.py

@@ -14,6 +14,7 @@
     build,
     collect,
     fork,
+    import_env,
     init,
     push,
     serve,
@@ -30,6 +31,9 @@
 
 # Register commands
 app.command(name="init", help="Initialize a new OpenEnv environment")(init.init)
+app.command(name="import", help="Import a third-party environment into OpenEnv")(
+    import_env.import_env
+)
 app.command(name="build", help="Build Docker images for OpenEnv environments")(
     build.build
 )