docs/source/auto_discovery.md

# Auto-Discovery

OpenEnv provides a HuggingFace-style auto-discovery API that makes it easy to work with environments without manual imports.

## Overview

The auto-discovery system provides two main classes:

- **`AutoEnv`**: Automatically loads and instantiates environment clients
- **`AutoAction`**: Automatically loads action classes for environments

Both classes work with:
- **Local packages**: Installed via `pip install openenv-<env-name>`
- **HuggingFace Hub**: Environments hosted on HuggingFace Spaces

## Quick Start

### Basic Usage

Instead of manually importing specific environment classes:

```python

# Old way - requires knowing the module path

from coding_env import CodingEnv, CodeAction

```

You can now use the auto-discovery API:

```python

from openenv import AutoEnv, AutoAction



# Create environment (returns async client)

env = AutoEnv.from_env("coding-env")



# Get action class

CodeAction = AutoAction.from_env("coding-env")



# Use with sync wrapper for simple scripts

with env.sync() as client:

    result = client.reset()

    action = CodeAction(code="print('Hello, OpenEnv!')")

    step_result = client.step(action)

```

## AutoEnv API

### `AutoEnv.from_env(name, **kwargs)`



Create an environment client from a name or HuggingFace Hub repository.



**Parameters:**

- `name`: Environment name or Hub repo ID

  - Local: `"coding"`, `"coding-env"`, `"coding_env"`
  - Hub: `"meta-pytorch/coding-env"`, `"username/env-name"`
- `base_url`: Optional base URL for HTTP connection
- `docker_image`: Optional Docker image name (overrides default)
- `container_provider`: Optional container provider
- `wait_timeout`: Timeout for container startup (default: 30s)
- `env_vars`: Optional environment variables for the container
- `**kwargs`: Additional arguments passed to the client class

**Returns:** Instance of the environment client class

**Examples:**

```python

from openenv import AutoEnv



# From installed package

env = AutoEnv.from_env("coding-env")



# From HuggingFace Hub

env = AutoEnv.from_env("meta-pytorch/coding-env")



# With custom configuration

env = AutoEnv.from_env(

    "coding",

    docker_image="my-coding-env:v2",

    wait_timeout=60.0,

    env_vars={"DEBUG": "1"}

)

```

### `AutoEnv.list_environments()`



List all available environments.



```python

from openenv import AutoEnv



AutoEnv.list_environments()
# Output:
# Available Environments:
# ----------------------------------------------------------------------
# coding         : Coding environment for OpenEnv (v0.1.0)
# echo           : echo_env environment (v0.1.0)

# browsergym     : BrowserGym environment (v0.1.0)

# ...

```



### `AutoEnv.get_env_info(name)`



Get detailed information about an environment.



```python

from openenv import AutoEnv



info = AutoEnv.get_env_info("coding")

print(f"Description: {info['description']}")

print(f"Version: {info['version']}")

print(f"Docker Image: {info['default_image']}")
print(f"Client Class: {info['env_class']}")

print(f"Action Class: {info['action_class']}")
```



### `AutoEnv.get_env_class(name)`



Get the environment class (not an instance).



```python

from openenv import AutoEnv



CodingEnv = AutoEnv.get_env_class("coding")

# Now you can instantiate it yourself with custom parameters

env = CodingEnv.from_docker_image("coding-env:latest", wait_timeout=60.0)

```

## AutoAction API

### `AutoAction.from_env(name)`



Get the Action class from an environment name or HuggingFace Hub repository.



**Parameters:**

- `name`: Environment name or Hub repo ID



**Returns:** Action class (not an instance!)



**Examples:**



```python

from openenv import AutoAction



# From installed package

CodeAction = AutoAction.from_env("coding-env")
action = CodeAction(code="print('Hello!')")

# From HuggingFace Hub
CodeAction = AutoAction.from_env("meta-pytorch/coding-env")



# Different name formats work

EchoAction = AutoAction.from_env("echo")
EchoAction = AutoAction.from_env("echo-env")

EchoAction = AutoAction.from_env("echo_env")

```



### `AutoAction.from_hub(env_name)`



Alias for `from_env()` for backward compatibility.

```python

from openenv import AutoAction



CodeAction = AutoAction.from_env("coding")

action = CodeAction(code="x = 5 + 3")

```

### `AutoAction.list_actions()`



List all available action classes.



```python

from openenv import AutoAction



AutoAction.list_actions()
# Output:
# Available Action Classes:
# ----------------------------------------------------------------------
# coding         : CodeAction
# echo           : EchoAction
# browsergym     : BrowsergymAction
# ...
```



### `AutoAction.get_action_info(name)`



Get detailed information about an action class.



```python

from openenv import AutoAction



info = AutoAction.get_action_info("coding")

print(f"Action Class: {info['action_class']}")

print(f"Module: {info['module']}")

```

## HuggingFace Hub Integration

### Loading from HuggingFace Spaces

AutoEnv can automatically connect to environments running on HuggingFace Spaces:

```python

from openenv import AutoEnv, AutoAction



# Load from HuggingFace Space

env = AutoEnv.from_env("username/coding-env-test")



# Get action class

CodeAction = AutoAction.from_env("username/coding-env-test")



# Use with sync wrapper

with env.sync() as client:

    result = client.reset()

    action = CodeAction(code="print('Hello from HF Space!')")

    step_result = client.step(action)

    print(f"Output: {step_result.observation.stdout}")

```

The system automatically:
1. Detects HuggingFace repo IDs (format: `username/repo-name`)
2. Resolves the Space URL (e.g., `https://username-repo-name.hf.space`)
3. Checks if the Space is running and accessible
4. Installs the environment package using `git+` URL (prompts for confirmation)
5. Connects to the running Space

### Security: Remote Code Installation

When loading environments from HuggingFace Hub, AutoEnv needs to install Python code from the remote repository. Since this executes code from the internet, AutoEnv will prompt for confirmation before installing:

```

============================================================

SECURITY WARNING: Remote Code Installation

============================================================

You are about to install code from a remote repository:

  Repository: username/coding-env-test

  Source: https://huggingface.co/spaces/username/coding-env-test



This will execute code from the internet on your machine.

Only proceed if you trust the source.

============================================================



Do you want to proceed? [y/N]:

```

To skip the confirmation prompt, you can either:

1. **Use the `trust_remote_code` parameter:**
   ```python

   env = AutoEnv.from_env("username/coding-env", trust_remote_code=True)

   ```

2. **Set the environment variable:**
   ```bash

   export OPENENV_TRUST_REMOTE_CODE=1

   python your_script.py

   ```

### Package Installation

AutoEnv uses `uv pip` if available, otherwise falls back to standard `pip`. This ensures compatibility with different Python environments:

```bash

# If uv is installed, AutoEnv uses:

uv pip install git+https://huggingface.co/spaces/username/coding-env



# Otherwise, it uses:

pip install git+https://huggingface.co/spaces/username/coding-env

```

## Complete Workflow Example

Here's a complete example showing the auto-discovery workflow:

```python

from openenv import AutoEnv, AutoAction



# 1. List available environments

print("Available environments:")

AutoEnv.list_environments()



# 2. Create environment and get action class

env = AutoEnv.from_env("coding-env")

CodeAction = AutoAction.from_env("coding-env")



# 3. Use with sync wrapper for simple scripts

with env.sync() as client:

    # Reset environment

    result = client.reset()

    print(f"Environment ready: {result.observation}")



    # Execute actions

    action = CodeAction(code="""

def fibonacci(n):

    if n <= 1:

        return n

    return fibonacci(n-1) + fibonacci(n-2)



print(f"Fibonacci(10) = {fibonacci(10)}")

""")



    step_result = client.step(action)

    print(f"Output:\n{step_result.observation.stdout}")

```

For async usage (recommended for production):

```python

import asyncio

from coding_env import CodingEnv, CodeAction



async def main():

    async with CodingEnv(base_url="http://localhost:8000") as client:

        result = await client.reset()

        result = await client.step(CodeAction(code="print('async!')"))

        print(result.observation.stdout)



asyncio.run(main())

```

## Error Handling

The auto-discovery API provides helpful error messages:

```python

from openenv import AutoEnv



try:

    env = AutoEnv.from_env("nonexistent-env")

except ValueError as e:

    print(e)

    # Output:

    # Unknown environment 'nonexistent'.

    # Did you mean: coding?

    # Available environments: atari, browsergym, chat, coding, ...

```

For typos, it suggests similar environment names:

```python

try:

    env = AutoEnv.from_env("cooding-env")  # Typo

except ValueError as e:

    print(e)

    # Output:

    # Unknown environment 'cooding'.

    # Did you mean: coding?

    # Available environments: ...

```

## Flexible Name Formats

AutoEnv accepts multiple name formats:

```python

from openenv import AutoEnv



# All of these work and refer to the same environment:

env = AutoEnv.from_env("coding")           # Simple name

env = AutoEnv.from_env("coding-env")       # With suffix

env = AutoEnv.from_env("coding_env")       # With underscore

env = AutoEnv.from_env("coding-env:latest") # With tag (ignored)

```

## How It Works

The auto-discovery system works by:

1. **Package Discovery**: Uses `importlib.metadata` to find installed `openenv-*` packages
2. **Manifest Loading**: Reads `openenv.yaml` files from package resources
3. **Caching**: Caches discovery results for performance
4. **Lazy Loading**: Only imports classes when actually needed
5. **Hub Support**: Downloads and installs packages from HuggingFace Hub on-demand

### Environment Packages

Environments are distributed as installable Python packages:

```bash

# Install an environment

pip install openenv-coding-env



# Now it's automatically discoverable

python -c "from openenv import AutoEnv; AutoEnv.list_environments()"

```

Each environment package includes:
- Client classes (e.g., `CodingEnv`)
- Action/Observation models (e.g., `CodeAction`, `CodeObservation`)
- Server Docker image
- `openenv.yaml` manifest describing the environment

### Manifest Format

Each environment includes an `openenv.yaml` file:

```yaml

name: coding_env

version: 0.1.0

description: Coding environment for OpenEnv



client:

  class_name: CodingEnv

  module: coding_env.client



action:

  class_name: CodeAction

  module: coding_env.client



observation:

  class_name: CodeObservation

  module: coding_env.client



default_image: coding-env:latest

spec_version: 1

```

## Benefits

✅ **Simple**: No need to know which module to import from
✅ **Flexible**: Works with local packages and HuggingFace Hub
✅ **Discoverable**: List and explore available environments
✅ **Type-Safe**: Returns properly typed environment classes
✅ **HuggingFace-style**: Familiar API for ML practitioners
✅ **Performant**: Caching and lazy loading for efficiency

## See Also

- [Environment Builder Guide](auto_getting_started/environment-builder.md) - How to create your own environments
- [Core API Documentation](core.md) - Low-level API details
- [HuggingFace Hub](https://huggingface.co/meta-pytorch) - Pre-built environments