openenv 0.4.2__tar.gz → 0.6.0__tar.gz

{openenv-0.4.2/src/openenv.egg-info → openenv-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openenv
-Version: 0.4.2
+Version: 0.6.0
 Summary: A unified framework for reinforcement learning environments
 License-Expression: BSD-3-Clause
 Requires-Python: >=3.10
@@ -8,6 +8,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: fastapi>=0.116.0
 Requires-Dist: pydantic>=2.0.0
+Requires-Dist: packaging>=24.2
 Requires-Dist: typing_extensions>=4.0.0
 Requires-Dist: uvicorn>=0.24.0
 Requires-Dist: requests>=2.25.0
@@ -31,8 +32,12 @@ Requires-Dist: azure-identity>=1.23.0; extra == "aca"
 Provides-Extra: modal
 Requires-Dist: modal>=1.4.0; extra == "modal"
 Requires-Dist: pyyaml>=6.0; extra == "modal"
+Provides-Extra: novita
+Requires-Dist: novita-sandbox>=2.1.1; extra == "novita"
 Provides-Extra: inspect
 Requires-Dist: inspect-ai>=0.3.0; extra == "inspect"
+Provides-Extra: harbor
+Requires-Dist: harbor[beam,blaxel,cua,cwsandbox,daytona,e2b,ec2,gke,islo,modal,novita,opensandbox,runloop,use-computer]>=0.22.0; python_version >= "3.12" and extra == "harbor"
 Dynamic: license-file
 
 # OpenEnv: Agentic Execution Environments
@@ -395,6 +400,9 @@ See the [Oumi example](https://github.com/oumi-ai/oumi/blob/main/notebooks/Oumi%
 ### Lightning AI
 [Lightning AI templates](https://lightning.ai/templates?section=featured&query=openenv)
 
+### Miles
+See the [Terminal-Bench-2 GRPO example](https://github.com/radixark/miles/tree/main/examples/experimental/openenv) on how to train on OpenEnv environments with Miles.
+
 ## Example Environments
 
 | Environment | Description |
@@ -409,11 +417,11 @@ See the [Oumi example](https://github.com/oumi-ai/oumi/blob/main/notebooks/Oumi%
 
 ## Community Support & Acknowledgments
 
-OpenEnv is governed by a technical committee that coordinates project direction, major technical decisions, RFCs, and release planning through the public issue tracker, pull requests, and RFC process. Current committee members: Meta-PyTorch, Reflection, Unsloth, Modal, Prime Intellect, Nvidia, Mercor, Fleet AI, Microsoft, Hugging Face, and RadixArk.
+OpenEnv is governed by a technical committee that coordinates project direction, major technical decisions, RFCs, and release planning through the public issue tracker, pull requests, and RFC process. Current committee members: Meta-PyTorch, Reflection, Unsloth, Modal, Prime Intellect, Nvidia, Mercor, Fleet AI, Microsoft, Hugging Face, RadixArk, and Nebius.
 
 The project is also supported by a broader community of organizations. If you would like to add your project or organization here, please open a pull request for maintainer review.
 
-Supporters include: [Meta-PyTorch](https://github.com/meta-pytorch), [Hugging Face](https://huggingface.co), [Scaler AI Labs](https://scalerailabs.com), [Patronus AI](https://patronus.ai), [Surge AI](https://surgehq.ai), [LastMile AI](https://www.lastmileai.dev), [Unsloth](https://unsloth.ai), [Reflection](https://reflection.ai), [vLLM](https://vllm.ai), [SkyRL](https://skyrl.readthedocs.io) (UC-Berkeley), [Lightning AI](https://lightning.ai), [Axolotl AI](https://github.com/axolotl-ai-cloud/axolotl), [Stanford Scaling Intelligence Lab](https://scalingintelligence.stanford.edu/), [Mithril](https://mithril.ai), [OpenMined](https://openmined.org/), [Fleet AI](https://fleetai.com), [Halluminate](https://halluminate.ai/), [Turing](https://www.turing.com/), [Scale AI](https://scale.com/), [Scorecard](https://www.scorecard.io/), [Snorkel AI](https://snorkel.ai/), [SGLang](https://github.com/sgl-project/sglang), [Miles](https://github.com/radixark/miles)
+Supporters include: [Meta-PyTorch](https://github.com/meta-pytorch), [Hugging Face](https://huggingface.co), [Scaler AI Labs](https://scalerailabs.com), [Patronus AI](https://patronus.ai), [Surge AI](https://surgehq.ai), [LastMile AI](https://www.lastmileai.dev), [Unsloth](https://unsloth.ai), [Reflection](https://reflection.ai), [vLLM](https://vllm.ai), [SkyRL](https://skyrl.readthedocs.io) (UC-Berkeley), [Lightning AI](https://lightning.ai), [Axolotl AI](https://github.com/axolotl-ai-cloud/axolotl), [Stanford Scaling Intelligence Lab](https://scalingintelligence.stanford.edu/), [Mithril](https://mithril.ai), [OpenMined](https://openmined.org/), [Fleet AI](https://fleetai.com), [Halluminate](https://halluminate.ai/), [Turing](https://www.turing.com/), [Scale AI](https://scale.com/), [Scorecard](https://www.scorecard.io/), [Snorkel AI](https://snorkel.ai/), [SGLang](https://github.com/sgl-project/sglang), [Miles](https://github.com/radixark/miles), [Nebius](https://nebius.com)
 
 And we'd also like to acknowledge the team at Farama Foundation as the OpenEnv API was heavily inspired by the work you all have done on Gymnasium. Cheers!
 

{openenv-0.4.2 → openenv-0.6.0}/README.md

@@ -358,6 +358,9 @@ See the [Oumi example](https://github.com/oumi-ai/oumi/blob/main/notebooks/Oumi%
 ### Lightning AI
 [Lightning AI templates](https://lightning.ai/templates?section=featured&query=openenv)
 
+### Miles
+See the [Terminal-Bench-2 GRPO example](https://github.com/radixark/miles/tree/main/examples/experimental/openenv) on how to train on OpenEnv environments with Miles.
+
 ## Example Environments
 
 | Environment | Description |
@@ -372,11 +375,11 @@ See the [Oumi example](https://github.com/oumi-ai/oumi/blob/main/notebooks/Oumi%
 
 ## Community Support & Acknowledgments
 
-OpenEnv is governed by a technical committee that coordinates project direction, major technical decisions, RFCs, and release planning through the public issue tracker, pull requests, and RFC process. Current committee members: Meta-PyTorch, Reflection, Unsloth, Modal, Prime Intellect, Nvidia, Mercor, Fleet AI, Microsoft, Hugging Face, and RadixArk.
+OpenEnv is governed by a technical committee that coordinates project direction, major technical decisions, RFCs, and release planning through the public issue tracker, pull requests, and RFC process. Current committee members: Meta-PyTorch, Reflection, Unsloth, Modal, Prime Intellect, Nvidia, Mercor, Fleet AI, Microsoft, Hugging Face, RadixArk, and Nebius.
 
 The project is also supported by a broader community of organizations. If you would like to add your project or organization here, please open a pull request for maintainer review.
 
-Supporters include: [Meta-PyTorch](https://github.com/meta-pytorch), [Hugging Face](https://huggingface.co), [Scaler AI Labs](https://scalerailabs.com), [Patronus AI](https://patronus.ai), [Surge AI](https://surgehq.ai), [LastMile AI](https://www.lastmileai.dev), [Unsloth](https://unsloth.ai), [Reflection](https://reflection.ai), [vLLM](https://vllm.ai), [SkyRL](https://skyrl.readthedocs.io) (UC-Berkeley), [Lightning AI](https://lightning.ai), [Axolotl AI](https://github.com/axolotl-ai-cloud/axolotl), [Stanford Scaling Intelligence Lab](https://scalingintelligence.stanford.edu/), [Mithril](https://mithril.ai), [OpenMined](https://openmined.org/), [Fleet AI](https://fleetai.com), [Halluminate](https://halluminate.ai/), [Turing](https://www.turing.com/), [Scale AI](https://scale.com/), [Scorecard](https://www.scorecard.io/), [Snorkel AI](https://snorkel.ai/), [SGLang](https://github.com/sgl-project/sglang), [Miles](https://github.com/radixark/miles)
+Supporters include: [Meta-PyTorch](https://github.com/meta-pytorch), [Hugging Face](https://huggingface.co), [Scaler AI Labs](https://scalerailabs.com), [Patronus AI](https://patronus.ai), [Surge AI](https://surgehq.ai), [LastMile AI](https://www.lastmileai.dev), [Unsloth](https://unsloth.ai), [Reflection](https://reflection.ai), [vLLM](https://vllm.ai), [SkyRL](https://skyrl.readthedocs.io) (UC-Berkeley), [Lightning AI](https://lightning.ai), [Axolotl AI](https://github.com/axolotl-ai-cloud/axolotl), [Stanford Scaling Intelligence Lab](https://scalingintelligence.stanford.edu/), [Mithril](https://mithril.ai), [OpenMined](https://openmined.org/), [Fleet AI](https://fleetai.com), [Halluminate](https://halluminate.ai/), [Turing](https://www.turing.com/), [Scale AI](https://scale.com/), [Scorecard](https://www.scorecard.io/), [Snorkel AI](https://snorkel.ai/), [SGLang](https://github.com/sgl-project/sglang), [Miles](https://github.com/radixark/miles), [Nebius](https://nebius.com)
 
 And we'd also like to acknowledge the team at Farama Foundation as the OpenEnv API was heavily inspired by the work you all have done on Gymnasium. Cheers!
 

{openenv-0.4.2 → openenv-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "openenv"
-version = "0.4.2"
+version = "0.6.0"
 description = "A unified framework for reinforcement learning environments"
 readme = "README.md"
 license = "BSD-3-Clause"
@@ -16,6 +16,7 @@ dependencies = [
     # individual environment pyproject.toml files
     "fastapi>=0.116.0",
     "pydantic>=2.0.0",
+    "packaging>=24.2",
     "typing_extensions>=4.0.0",
     "uvicorn>=0.24.0",
     "requests>=2.25.0",
@@ -52,9 +53,23 @@ modal = [
     "modal>=1.4.0",
     "pyyaml>=6.0",
 ]
+novita = [
+    "novita-sandbox>=2.1.1",
+]
 inspect = [
     "inspect-ai>=0.3.0",
 ]
+harbor = [
+    # Every sandbox backend. Bare `harbor` gives one that lists all 23 backends and can
+    # instantiate none of them: each raises MissingExtraError from its constructor, which
+    # surfaces as a failed rollout rather than as a missing dependency.
+    #
+    # Not `harbor[cloud]`, which is unsatisfiable: it pulls `langsmith[sandbox]`
+    # (websockets>=15) and `tensorlake` (websockets>=13,<14) together.
+    #
+    # Harbor requires Python >= 3.12, so this extra is excluded from the 3.11 CI leg.
+    "harbor[e2b,modal,daytona,gke,ec2,runloop,novita,blaxel,beam,islo,opensandbox,cwsandbox,use-computer,cua]>=0.22.0; python_version >= '3.12'",
+]
 
 [project.scripts]
 openenv = "openenv.cli.__main__:main"
@@ -66,6 +81,8 @@ include-package-data = true
 [tool.setuptools.package-data]
 "openenv.cli" = ["templates/**/*"]
 "openenv.cli.importers" = ["templates/**/*"]
+"openenv.validation" = ["policies/*.json", "schemas/*.json"]
+"openenv.discovery" = ["schemas/**/*.json"]
 
 [tool.setuptools.exclude-package-data]
 "*" = ["*.pyc", "*.pyo", "__pycache__/*"]
@@ -106,6 +123,7 @@ dev = [
     "usort>=1.1.0",
     "pytest>=7.0",
     "pytest-asyncio>=0.21",
+    "jsonschema>=4.20.0",
 ]
 
 [tool.usort]

{openenv-0.4.2 → openenv-0.6.0}/src/openenv/auto/_discovery.py

@@ -20,8 +20,9 @@ import importlib.metadata
 import importlib.resources
 import json
 import logging
+import os
 import re
-import tempfile
+import stat
 from dataclasses import asdict, dataclass
 from pathlib import Path
 from typing import Any, Type
@@ -336,6 +337,118 @@ def _create_env_info_from_package(
     )
 
 
+def _default_cache_file() -> Path:
+    """
+    Return the per-user discovery cache file path.
+
+    Uses a per-user cache directory (``$XDG_CACHE_HOME`` or ``~/.cache``) rather than a
+    shared, world-writable temporary directory. A fixed path under the shared temp dir
+    lets another local user pre-create the cache file and redirect discovery to
+    attacker-controlled import paths (`import_module` on a cached `client_module_path`).
+    Per the XDG Base Directory specification, relative `XDG_CACHE_HOME` values are
+    ignored so an untrusted working tree cannot supply a victim-owned cache file.
+    The fallback home must itself be absolute; otherwise discovery fails closed.
+    """
+    base = os.environ.get("XDG_CACHE_HOME")
+    if base and Path(base).is_absolute():
+        root = Path(base)
+    else:
+        home = Path.home()
+        if not home.is_absolute():
+            raise RuntimeError(
+                "discovery cache requires an absolute home directory when "
+                "XDG_CACHE_HOME is unset or relative"
+            )
+        root = home / ".cache"
+    return root / "openenv" / "discovery_cache.json"
+
+
+def _is_trusted_stat(info: os.stat_result) -> bool:
+    """
+    Return whether the file *info* describes is safe to load.
+
+    On POSIX the file must be owned by the current user and not writable by group or
+    others, so a cache file planted by another user is ignored rather than trusted.
+
+    Args:
+        info (`os.stat_result`):
+            Metadata for the file being considered.
+
+    Returns:
+        `bool`: `True` if the file is owned by the current user and not
+        group/other-writable (always `True` on non-POSIX platforms).
+    """
+    if os.name != "posix":
+        return True
+    return info.st_uid == os.getuid() and not (
+        info.st_mode & (stat.S_IWGRP | stat.S_IWOTH)
+    )
+
+
+def _is_trusted_cache_file(path: Path) -> bool:
+    """
+    Return whether *path* is safe to load.
+
+    Prefer `_open_trusted_cache`, which checks the descriptor it hands back. This
+    variant resolves the path a second time, so on its own it cannot promise that
+    the file inspected is the file later read.
+
+    Args:
+        path (`Path`):
+            The cache file to check.
+
+    Returns:
+        `bool`: `True` if the file is owned by the current user and not
+        group/other-writable (always `True` on non-POSIX platforms).
+    """
+    if os.name != "posix":
+        return True
+    try:
+        return _is_trusted_stat(path.stat())
+    except OSError:
+        return False
+
+
+def _open_trusted_cache(path: Path) -> int | None:
+    """
+    Open *path* for reading and return the descriptor only if it is trustworthy.
+
+    Checking a path and then opening it are two separate resolutions, and an
+    attacker who can write in the cache directory can swap the file for a symlink
+    in between, so the file that was vetted is not the file that gets read.
+    ``O_NOFOLLOW`` refuses a symlink outright and ``fstat`` inspects the descriptor
+    itself, which makes the ownership check and the read the same object.
+
+    Args:
+        path (`Path`):
+            The cache file to open.
+
+    Returns:
+        `int` or `None`: an open read-only descriptor the caller must close, or
+        `None` if the file is missing, is a symlink, is not a regular file, or
+        is not owned by the current user.
+    """
+    # O_NONBLOCK matters before the descriptor can be inspected: opening a FIFO
+    # read-only otherwise waits for a writer that an attacker simply never
+    # provides, so discovery hangs before any check runs. It has no effect on a
+    # regular file, which is the only thing accepted here anyway.
+    flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0)
+    try:
+        fd = os.open(path, flags)
+    except OSError:
+        # Missing, unreadable, or a symlink (ELOOP under O_NOFOLLOW).
+        return None
+    try:
+        info = os.fstat(fd)
+        if not stat.S_ISREG(info.st_mode) or not _is_trusted_stat(info):
+            os.close(fd)
+            return None
+    except OSError:
+        os.close(fd)
+        return None
+    return fd
+
+
 class EnvironmentDiscovery:
     """
     Auto-discovery system for OpenEnv environments using installed packages.
@@ -346,7 +459,7 @@ class EnvironmentDiscovery:
     def __init__(self):
         """Initialize discovery system."""
         self._cache: dict[str, EnvironmentInfo] | None = None
-        self._cache_file = Path(tempfile.gettempdir()) / "openenv_discovery_cache.json"
+        self._cache_file = _default_cache_file()
 
     def _discover_installed_packages(self) -> dict[str, EnvironmentInfo]:
         """
@@ -408,11 +521,22 @@ class EnvironmentDiscovery:
         Returns:
             Dictionary of env_key -> EnvironmentInfo, or None if cache invalid
         """
-        if not self._cache_file.exists():
+        # Only trust a cache file owned by the current user. This prevents another
+        # local user from planting a file that would redirect discovery (and the
+        # subsequent import_module) to attacker-controlled modules/classes. The
+        # descriptor is what gets vetted and then read, so the file cannot be
+        # swapped for a symlink after the check.
+        fd = _open_trusted_cache(self._cache_file)
+        if fd is None:
+            if self._cache_file.exists():
+                logger.warning(
+                    f"Ignoring discovery cache {self._cache_file}: not owned by "
+                    "the current user, writable by group/others, or a symlink."
+                )
             return None
 
         try:
-            with open(self._cache_file, "r") as f:
+            with os.fdopen(fd, "r") as f:
                 cache_data = json.load(f)
 
             # Reconstruct EnvironmentInfo objects
@@ -437,8 +561,30 @@ class EnvironmentDiscovery:
             for env_key, env_info in environments.items():
                 cache_data[env_key] = asdict(env_info)
 
-            with open(self._cache_file, "w") as f:
-                json.dump(cache_data, f, indent=2)
+            self._cache_file.parent.mkdir(parents=True, exist_ok=True)
+            # Write a new file and move it into place rather than writing
+            # through whatever already sits at the destination. A mode passed to
+            # `os.open` only applies when it creates the file, so truncating an
+            # existing group/world-writable cache would keep that mode and
+            # publish what was just written; and `os.replace` is atomic, so a
+            # reader never observes a half-written cache when serialization
+            # fails part way. `O_EXCL` requires the temporary name to be new,
+            # and 0600 is applied at creation so the umask cannot widen it.
+            tmp_path = self._cache_file.with_name(
+                f"{self._cache_file.name}.{os.getpid()}.tmp"
+            )
+            flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
+            fd = os.open(tmp_path, flags, 0o600)
+            try:
+                with os.fdopen(fd, "w") as f:
+                    json.dump(cache_data, f, indent=2)
+                os.replace(tmp_path, self._cache_file)
+            except BaseException:
+                try:
+                    os.unlink(tmp_path)
+                except OSError:
+                    pass
+                raise
 
         except Exception as e:
             logger.warning(f"Failed to save discovery cache: {e}")
@@ -575,8 +721,12 @@ def get_discovery() -> EnvironmentDiscovery:
 
 
 def reset_discovery() -> None:
-    """Reset the global discovery instance (useful for testing)."""
+    """Drop the global discovery singleton (useful for testing).
+
+    Does **not** delete the on-disk cache. The cache is now a persistent
+    per-user file under `$XDG_CACHE_HOME`; wiping it belongs on an explicit
+    [`EnvironmentDiscovery.clear_cache`][] call so test fixtures that only
+    need a fresh singleton cannot clobber a developer's real cache.
+    """
     global _global_discovery
-    if _global_discovery is not None:
-        _global_discovery.clear_cache()
     _global_discovery = None

{openenv-0.4.2 → openenv-0.6.0}/src/openenv/cli/__main__.py

@@ -12,8 +12,10 @@ import sys
 import typer
 from openenv.cli.commands import (
     build,
+    catalog,
     collect,
     fork,
+    harbor,
     import_env,
     init,
     push,
@@ -37,9 +39,14 @@ app.command(name="import", help="Import a third-party environment into OpenEnv")
 app.command(name="build", help="Build Docker images for OpenEnv environments")(
     build.build
 )
-app.command(
-    name="validate", help="Validate environment structure and deployment readiness"
-)(validate.validate)
+app.add_typer(
+    harbor.app,
+    name="harbor",
+    help="Run Harbor tasks with token-level capture (requires: pip install openenv[harbor])",
+)
+app.command(name="validate", help="Validate a package against the OpenEnv quality bar")(
+    validate.validate
+)
 app.command(
     name="push",
     help="Push an OpenEnv environment to Hugging Face Spaces or custom registry",
@@ -60,6 +67,8 @@ app.command(
     name="collect",
     help="Collect rollouts from a deployed OpenEnv environment",
 )(collect.collect)
+app.add_typer(catalog.app, name="catalog")
+app.command(name="discover")(catalog.discover)
 
 
 # Entry point for setuptools

openenv-0.6.0/src/openenv/cli/commands/catalog.py

@@ -0,0 +1,121 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Metadata catalog production and inspection. No environment is instantiated."""
+
+import json
+from pathlib import Path
+
+import typer
+from openenv.discovery import (
+    build_catalog,
+    CatalogError,
+    load_catalog,
+    resolve_entry,
+    search_catalog,
+    write_catalog,
+)
+
+app = typer.Typer(
+    help="Build and inspect versioned, metadata-only environment catalogs."
+)
+
+
+@app.command("build")
+def build(
+    repository: Path = typer.Option(..., help="Local Git repository to read."),
+    repository_uri: str = typer.Option(..., help="Declared GitHub HTTPS clone URI."),
+    publisher: str = typer.Option(..., help="Explicit catalog publication authority."),
+    output: Path = typer.Option(..., help="Destination snapshot JSON."),
+    revision: str = typer.Option("HEAD", help="Source commit or ref."),
+    root: str = typer.Option("envs", help="Direct-child environment inventory root."),
+    namespace: str = typer.Option("openenv", help="Publisher-owned namespace."),
+) -> None:
+    """Build from committed metadata; uncommitted files and candidate code are not used."""
+    try:
+        snapshot = build_catalog(
+            repository,
+            repository_uri=repository_uri,
+            publisher=publisher,
+            namespace=namespace,
+            revision=revision,
+            root=root,
+        )
+        write_catalog(snapshot, output)
+    except CatalogError as error:
+        typer.echo(f"Catalog error: {error}", err=True)
+        raise typer.Exit(1) from error
+    typer.echo(
+        f"{len(snapshot.entries)} records, snapshot {snapshot.digest}, "
+        f"complete={str(snapshot.complete).lower()}",
+        err=True,
+    )
+    for issue in snapshot.issues:
+        typer.echo(f"{issue.severity}: {issue.path}: {issue.message}", err=True)
+    if not snapshot.complete:
+        raise typer.Exit(1)
+
+
+@app.command("inspect")
+def inspect(
+    identifier: str = typer.Argument(..., help="Exact revision-card identifier."),
+    catalog: Path = typer.Option(..., help="Complete configured snapshot."),
+) -> None:
+    """Return the complete selected entry without guessing or fetching a URL."""
+    try:
+        entry = resolve_entry(load_catalog(catalog), identifier)
+    except CatalogError as error:
+        typer.echo(f"Catalog error: {error}", err=True)
+        raise typer.Exit(1) from error
+    typer.echo(entry.model_dump_json(by_alias=True, exclude_none=True, indent=2))
+
+
+def discover(
+    query: str = typer.Argument("", help="Task to find an environment for."),
+    catalog: Path = typer.Option(
+        ..., help="Complete, explicitly configured local snapshot."
+    ),
+    limit: int = typer.Option(20, min=1, max=1000),
+    filter: list[str] = typer.Option([], "--filter", help="Exact field=value filter."),
+    as_json: bool = typer.Option(False, "--json", help="Emit complete ARD entry data."),
+) -> None:
+    """Find unfamiliar environments by task before any installation or execution."""
+    filters = {}
+    for item in filter:
+        key, separator, value = item.partition("=")
+        if not separator or not key or key in filters:
+            typer.echo(
+                "Catalog error: filters must be distinct field=value pairs", err=True
+            )
+            raise typer.Exit(1)
+        filters[key] = value
+    try:
+        snapshot = load_catalog(catalog)
+        matches = search_catalog(snapshot, query, filters=filters, limit=limit)
+    except CatalogError as error:
+        typer.echo(f"Catalog error: {error}", err=True)
+        raise typer.Exit(1) from error
+    if as_json:
+        results = [
+            {
+                **match.entry.model_dump(by_alias=True, exclude_none=True, mode="json"),
+                "score": match.score,
+            }
+            for match in matches
+        ]
+        typer.echo(
+            json.dumps(
+                {"results": results, "snapshot": snapshot.digest, "metadataOnly": True},
+                indent=2,
+                ensure_ascii=False,
+            )
+        )
+        return
+    for match in matches:
+        card = match.entry.data
+        typer.echo(f"{match.entry.display_name}: {card.description}")
+        typer.echo(f"  source: {card.source.uri}")
+        typer.echo(f"  path: {card.source.path}")
+        typer.echo(f"  revision: {card.source.revision}")
+        typer.echo(f"  license: {card.license}; artifact: {card.artifact_availability}")
+        typer.echo(f"  identifier: {match.entry.identifier}")
+    typer.echo("Metadata only. Execution approval remains a separate decision.")

{openenv-0.4.2 → openenv-0.6.0}/src/openenv/cli/commands/collect.py

@@ -141,7 +141,7 @@ def _build_llm_model_step(
     model: str,
     *,
     llm_endpoint: str | None,
-    llm_port: int,
+    llm_port: int | None,
     temperature: float,
     max_tokens: int,
     system_prompt: str | None = None,
@@ -152,15 +152,19 @@ def _build_llm_model_step(
         # Self-hosted OpenAI-compatible endpoint (vLLM, TGI, Ollama, ...).
         from openenv.core.llm_client import OpenAIClient
 
-        client: LLMClient = OpenAIClient(
-            endpoint=llm_endpoint,
-            port=llm_port,
-            model=model,
-            api_key=os.getenv("OPENAI_API_KEY") or "not-needed",
-            system_prompt=effective_system_prompt,
-            temperature=temperature,
-            max_tokens=max_tokens,
-        )
+        try:
+            client: LLMClient = OpenAIClient(
+                endpoint=llm_endpoint,
+                port=llm_port,
+                model=model,
+                api_key=os.getenv("OPENAI_API_KEY") or "not-needed",
+                system_prompt=effective_system_prompt,
+                temperature=temperature,
+                max_tokens=max_tokens,
+            )
+        except ValueError as exc:
+            raise typer.BadParameter(str(exc), param_hint="--llm-endpoint") from exc
+        console.print(f"[cyan]LLM endpoint:[/cyan] {client.base_url}")
     else:
         client = create_llm_client(
             provider=provider,
@@ -280,13 +284,23 @@ def collect(
         str | None,
         typer.Option(
             "--llm-endpoint",
-            help="OpenAI-compatible endpoint URL (for self-hosted vLLM/TGI/Ollama).",
+            help=(
+                "Base URL of a self-hosted OpenAI-compatible server "
+                "(vLLM/TGI/Ollama), e.g. http://localhost:8000. /v1 is appended "
+                "when the URL has no path; a URL with a path is used as-is."
+            ),
         ),
     ] = None,
     llm_port: Annotated[
-        int,
-        typer.Option("--llm-port", help="Port for self-hosted LLM endpoint."),
-    ] = 8000,
+        int | None,
+        typer.Option(
+            "--llm-port",
+            help=(
+                "Port appended to --llm-endpoint when the URL does not include one. "
+                "No default: earlier releases assumed 8000."
+            ),
+        ),
+    ] = None,
     temperature: Annotated[
         float, typer.Option("--temperature", help="Sampling temperature.")
     ] = 0.2,
@@ -364,6 +378,20 @@ def collect(
     factory = _build_session_factory(
         env, base_url, dataset_config=parsed_dataset_config
     )
+
+    if uses_llm_teacher:
+        model_step = _build_llm_model_step(
+            provider=provider,
+            model=model,  # type: ignore[arg-type]  # validated above
+            llm_endpoint=llm_endpoint,
+            llm_port=llm_port,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            system_prompt=system_prompt,
+        )
+    else:
+        model_step = _build_scripted_model_step()
+
     serializer = RolloutSerializer(output_dir)
     serializer.write_metadata(
         {
@@ -379,19 +407,6 @@ def collect(
         }
     )
 
-    if uses_llm_teacher:
-        model_step = _build_llm_model_step(
-            provider=provider,
-            model=model,  # type: ignore[arg-type]  # validated above
-            llm_endpoint=llm_endpoint,
-            llm_port=llm_port,
-            temperature=temperature,
-            max_tokens=max_tokens,
-            system_prompt=system_prompt,
-        )
-    else:
-        model_step = _build_scripted_model_step()
-
     should_keep = None if keep_losses else (lambda record: record.reward >= 0.0)
 
     collect_runner = CollectRunner(