dojo-openenv 0.1.5
Wrapper for dojo-sdk-client to use with OpenEnv
Requires Python: >=3.10

# Dojo OpenEnv

Wrapper for `dojo-sdk-client` to use with OpenEnv, enabling Dojo tasks to be used as OpenEnv-compatible environments for reinforcement learning.

## Overview

`dojo-openenv` provides a bridge between the Dojo RL environment framework and OpenEnv, allowing you to run Dojo tasks through the standard OpenEnv interface. This enables seamless integration of Dojo tasks with OpenEnv-based training pipelines and evaluation frameworks.

## Installation

```bash
uv add dojo-openenv
```

Or with pip:

```bash
pip install dojo-openenv
```

## Basic Usage

```python
from dojo_openenv import DojoEnvClient, DojoAction
from dojo_sdk_client.agents.anthropic_cua import AnthropicCUA

# Create an agent
agent = AnthropicCUA(
    model="claude-4-sonnet-20250514", image_context_length=4, verbose=False
)

# Initialize the environment with a task ID and API key
env = DojoEnvClient(
    task_id="2048/get-2048",
    api_key="your-api-key-here"
)

try:
    # Reset the environment
    result = env.reset()

    # Run steps until done
    while not result.done:
        # Get next action from AI agent
        action, reasoning, raw_response = agent.get_next_action(
            prompt=env.task_definition.instructions.user_prompt,
            history=result.observation.task_response.history,
            image=result.observation.screenshot_image,
        )

        # Wrap in DojoAction
        env_action = DojoAction(
            action=action, reasoning=reasoning, raw_response=raw_response
        )

        # Step the environment
        result = env.step(env_action)

        # Access observation and reward
        print(f"Reward: {result.reward}")
        print(f"State: {result.observation.task_response.state}")

finally:
    # Clean up
    env.close()
```

## Key Components

### `DojoEnvClient`

The main environment client that implements the OpenEnv `HTTPEnvClient` specification.

### `DojoAction`

Action wrapper that extends the OpenEnv `Action` base class with:

- `action`: A Dojo core action from `dojo-sdk-core` (e.g., `ClickAction`, `TypeAction`, etc.)
- `reasoning`: String describing the reasoning behind the action
- `raw_response`: Raw response from the agent (for debugging or logging)

### `DojoObservation`

Observation wrapper that extends the OpenEnv `Observation` base class with:

- `task_response`: The current task state from the Dojo client, which includes the task history and a current screenshot of the task environment.

## Documentation

For more information about Dojo tasks, actions, and the SDK, visit [docs.trydojo.ai](https://docs.trydojo.ai).

# Hosting OpenEnv Environments on Dojo

Dojo can host OpenEnv-compatible environments on managed Dojo infrastructure. Use the `DojoOpenEnvProvisioner` component to deploy environments found on the [OpenEnv Environment Hub](https://huggingface.co/collections/openenv/environment-hub).

## Basic Usage

```python
from dojo_openenv.provider import DojoOpenEnvProvisioner
from envs.openspiel_env.models import OpenSpielAction
from envs.openspiel_env.client import OpenSpielEnv

# Launch the environment on the Dojo infrastructure
env = DojoOpenEnvProvisioner.run_on_dojo(
    cls=OpenSpielEnv,
    image="openenv/openspiel-env",
    api_key="your-dojo-api-key",
    env_vars={"OPENSPIEL_GAME": "2048"}
)

try:
    # Reset the environment
    result = env.reset()

    while not result.done:
        # Choose a random action and submit it to the environment
        action = random.choice(result.observation.legal_actions)
        result = env.step(action)
finally:
    # Cleanup
    env.close()
```

## Key Components

### `DojoOpenEnvProvisioner`

Utility class which can be used to launch an environment on Dojo infrastructure.

**`DojoOpenEnvProvisioner.run_on_dojo(cls, image, api_key, env_vars=None)`**

- `cls`: OpenEnv environment client class to instantiate
- `image`: Docker image identifier (e.g., `"openenv/openspiel-env"`)
- `api_key`: Dojo API key
- `env_vars`: Optional environment variables dict

Returns an instance of `cls` connected to the Dojo-hosted container. Containers are cleaned up when the environment client is closed via `env.close()`, or when idle for a period of time.