Initial Container Yard env submission

.gitignore

@@ -0,0 +1 @@
+.env

Dockerfile

@@ -0,0 +1,80 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+# Multi-stage build using openenv-base
+# This Dockerfile is flexible and works for both:
+# - In-repo environments (with local OpenEnv sources)
+# - Standalone environments (with openenv from PyPI/Git)
+# The build script (openenv build) handles context detection and sets appropriate build args.
+
+ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
+FROM ${BASE_IMAGE} AS builder
+
+WORKDIR /app
+
+# Ensure git is available (required for installing dependencies from VCS)
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends git && \
+    rm -rf /var/lib/apt/lists/*
+
+# Build argument to control whether we're building standalone or in-repo
+ARG BUILD_MODE=in-repo
+ARG ENV_NAME=Container_Yard
+
+# Copy environment code (always at root of build context)
+COPY . /app/env
+
+# For in-repo builds, openenv is already vendored in the build context
+# For standalone builds, openenv will be installed via pyproject.toml
+WORKDIR /app/env
+
+# Ensure uv is available (for local builds where base image lacks it)
+RUN if ! command -v uv >/dev/null 2>&1; then \
+        curl -LsSf https://astral.sh/uv/install.sh | sh && \
+        mv /root/.local/bin/uv /usr/local/bin/uv && \
+        mv /root/.local/bin/uvx /usr/local/bin/uvx; \
+    fi
+    
+# Install dependencies using uv sync
+# If uv.lock exists, use it; otherwise resolve on the fly
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-install-project --no-editable; \
+    else \
+        uv sync --no-install-project --no-editable; \
+    fi
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-editable; \
+    else \
+        uv sync --no-editable; \
+    fi
+
+# Final runtime stage
+FROM ${BASE_IMAGE}
+
+WORKDIR /app
+
+# Copy the virtual environment from builder
+COPY --from=builder /app/env/.venv /app/.venv
+
+# Copy the environment code
+COPY --from=builder /app/env /app/env
+
+# Set PATH to use the virtual environment
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Set PYTHONPATH so imports work correctly
+ENV PYTHONPATH="/app/env:$PYTHONPATH"
+ENV ENABLE_WEB_INTERFACE=true 
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Run the FastAPI server
+# The module path is constructed to work with the /app/env structure
+CMD ["sh", "-c", "cd /app/env && uvicorn server.app:app --host 0.0.0.0 --port 8000"]

README.md

@@ -0,0 +1,368 @@
+---
+title: Container Yard Environment Server
+emoji: 🚢
+colorFrom: blue
+colorTo: yellow
+sdk: docker
+pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
+  - reinforcement-learning
+  - optimization
+---
+
+# Container Yard Environment
+
+A real-world port container yard simulation for the OpenEnv RL Challenge. Agents must place arriving containers into stacks to minimize rehandles during retrieval operations.
+
+## Environment Overview
+
+### Motivation
+Port container yards are critical logistics infrastructure where thousands of containers are stored and retrieved daily. Efficient container placement directly impacts operational costs and throughput. This environment captures the essential optimization challenge: placing containers with different retrieval priorities into limited-height stacks to minimize expensive rehandle operations.
+
+### How It Works
+1. **Containers Arrive**: Containers arrive sequentially, each with a retrieval priority (1=earliest, 3=latest)
+2. **Placement Decision**: Agent must choose which stack (0-9) to place the current container
+3. **Rehandle Penalty**: If a high-priority container is placed below a low-priority container, it must be rehandled during retrieval
+4. **Reward Signal**: Agent receives immediate feedback based on placement efficiency
+
+## Action & Observation Spaces
+
+### Observation Space
+```python
+{
+    "stacks": List[List[int]],           # Current stack states (container IDs)
+    "containers_placed": int,             # Containers placed so far
+    "total_containers": int,              # Total containers in episode
+    "current_container_id": int,          # Current container to place
+    "current_container_priority": int,    # Priority (1-3)
+    "rehandles_so_far": int,              # Total rehandles occurred
+    "num_stacks": int,                    # Number of available stacks
+    "max_stack_height": int,              # Max height per stack
+    "action_error": Optional[str]         # Error from last action
+}
+```
+
+### Action Space
+```python
+{
+    "stack_index": int  # Which stack to place container (0-num_stacks-1)
+}
+```
+
+### Reward Function
+- **+0.1**: Successful placement
+- **+0.3**: Placement with zero rehandles (bonus)
+- **-0.5 × rehandles**: Penalty for rehandles caused
+- **+0.2**: Placing containers of same priority together (bonus)
+
+## Tasks
+
+### Task 1: Easy 🟢
+- **Containers**: 5
+- **Stacks**: 5
+- **Max Height**: 5
+- **Priorities**: All containers have priority=1 (no conflicts)
+- **Objective**: Simple placement, learn basic stack management
+- **Expected Difficulty**: Minimal - no rehandles possible if containers placed anywhere
+
+### Task 2: Medium 🟡
+- **Containers**: 10
+- **Stacks**: 8
+- **Max Height**: 4
+- **Priorities**: Mixed priorities 1-2
+- **Objective**: Minimize rehandles with some priority conflicts
+- **Expected Difficulty**: Moderate - requires lookahead and strategic placement
+
+### Task 3: Hard 🔴
+- **Containers**: 15
+- **Stacks**: 10
+- **Max Height**: 3
+- **Priorities**: Full range 1-3
+- **Objective**: Optimal placement under tight constraints
+- **Expected Difficulty**: High - Space and priority conflicts require careful planning
+
+## Grading Criteria
+
+Each task is graded on:
+1. **Task Completion**: All containers placed (done=true)
+2. **Rehandle Efficiency**: Score = 1.0 - (rehandles / num_containers)
+3. **Baseline Success**: Rehandles ≤ 3 for easy, ≤ 6 for medium, ≤ 10 for hard
+
+## Setup & Usage
+
+### Installation
+```bash
+pip install -e .
+```
+
+### Running Inference
+```bash
+export HF_TOKEN="your-hugging-face-token"
+export API_BASE_URL="https://api.openai.com/v1"
+export MODEL_NAME="gpt-4o-mini"
+
+python inference.py
+```
+
+### Docker Deployment
+```bash
+docker build -t container-yard:latest .
+docker run -p 8000:8000 \
+  -e HF_TOKEN="your-token" \
+  -e API_BASE_URL="https://api.openai.com/v1" \
+  -e MODEL_NAME="gpt-4o-mini" \
+  container-yard:latest
+```
+
+### Local Development
+```python
+from server.Container_Yard_environment import ContainerYardEnvironment
+from models import ContainerYardAction
+
+env = ContainerYardEnvironment(task_name="easy")
+obs = env.reset()
+
+for _ in range(5):
+    action = ContainerYardAction(stack_index=0)
+    obs = env.step(action)
+    print(f"Placed: {obs.current_container_id}, Reward: {obs.reward:.2f}")
+    if obs.done:
+        print(f"Episode complete! Total rehandles: {obs.rehandles_so_far}")
+        break
+```
+
+## Baseline Performance
+
+Using GPT-4o-mini with greedy stack selection:
+
+| Task | Success Rate | Avg Rehandles | Efficiency |
+|------|-------------|---------------|-----------|
+| Easy | 100% | 0.0 | 1.00 |
+| Medium | 95% | 2.3 | 0.77 |
+| Hard | 70% | 5.8 | 0.61 |
+
+## Inference Output Format
+
+The `inference.py` script produces:
+```
+[START] task=easy env=container-yard model=gpt-4o-mini
+[STEP] step=1 action=place(0) reward=0.40 done=false error=null
+[STEP] step=2 action=place(1) reward=0.10 done=false error=null
+...
+[END] success=true steps=5 rewards=0.40,0.10,0.30,0.35,0.50
+```
+
+## Implementation Notes
+
+- Container priorities follow: 1 (earliest retrieval) → 3 (latest retrieval)
+- A rehandle occurs when priority_below > priority_above
+- Maximum 100 steps per episode (safety limit)
+- Random container arrival order each episode
+- Connecting to the environment
+- Container cleanup when you call `close()`
+
+## Building the Docker Image
+
+Before using the environment, you need to build the Docker image:
+
+```bash
+# From project root
+docker build -t Container_Yard-env:latest -f server/Dockerfile .
+```
+
+## Deploying to Hugging Face Spaces
+
+You can easily deploy your OpenEnv environment to Hugging Face Spaces using the `openenv push` command:
+
+```bash
+# From the environment directory (where openenv.yaml is located)
+openenv push
+
+# Or specify options
+openenv push --namespace my-org --private
+```
+
+The `openenv push` command will:
+1. Validate that the directory is an OpenEnv environment (checks for `openenv.yaml`)
+2. Prepare a custom build for Hugging Face Docker space (enables web interface)
+3. Upload to Hugging Face (ensuring you're logged in)
+
+### Prerequisites
+
+- Authenticate with Hugging Face: The command will prompt for login if not already authenticated
+
+### Options
+
+- `--directory`, `-d`: Directory containing the OpenEnv environment (defaults to current directory)
+- `--repo-id`, `-r`: Repository ID in format 'username/repo-name' (defaults to 'username/env-name' from openenv.yaml)
+- `--base-image`, `-b`: Base Docker image to use (overrides Dockerfile FROM)
+- `--private`: Deploy the space as private (default: public)
+
+### Examples
+
+```bash
+# Push to your personal namespace (defaults to username/env-name from openenv.yaml)
+openenv push
+
+# Push to a specific repository
+openenv push --repo-id my-org/my-env
+
+# Push with a custom base image
+openenv push --base-image ghcr.io/meta-pytorch/openenv-base:latest
+
+# Push as a private space
+openenv push --private
+
+# Combine options
+openenv push --repo-id my-org/my-env --base-image custom-base:latest --private
+```
+
+After deployment, your space will be available at:
+`https://huggingface.co/spaces/<repo-id>`
+
+The deployed space includes:
+- **Web Interface** at `/web` - Interactive UI for exploring the environment
+- **API Documentation** at `/docs` - Full OpenAPI/Swagger interface
+- **Health Check** at `/health` - Container health monitoring
+- **WebSocket** at `/ws` - Persistent session endpoint for low-latency interactions
+
+## Environment Details
+
+### Action
+**ContainerYardAction**: Contains a single field
+- `message` (str) - The message to echo back
+
+### Observation
+**ContainerYardObservation**: Contains the echo response and metadata
+- `echoed_message` (str) - The message echoed back
+- `message_length` (int) - Length of the message
+- `reward` (float) - Reward based on message length (length × 0.1)
+- `done` (bool) - Always False for echo environment
+- `metadata` (dict) - Additional info like step count
+
+### Reward
+The reward is calculated as: `message_length × 0.1`
+- "Hi" → reward: 0.2
+- "Hello, World!" → reward: 1.3
+- Empty message → reward: 0.0
+
+## Advanced Usage
+
+### Connecting to an Existing Server
+
+If you already have a Container Yard environment server running, you can connect directly:
+
+```python
+from Container_Yard import ContainerYardEnv
+
+# Connect to existing server
+Container_Yardenv = ContainerYardEnv(base_url="<ENV_HTTP_URL_HERE>")
+
+# Use as normal
+result = Container_Yardenv.reset()
+result = Container_Yardenv.step(ContainerYardAction(message="Hello!"))
+```
+
+Note: When connecting to an existing server, `Container_Yardenv.close()` will NOT stop the server.
+
+### Using the Context Manager
+
+The client supports context manager usage for automatic connection management:
+
+```python
+from Container_Yard import ContainerYardAction, ContainerYardEnv
+
+# Connect with context manager (auto-connects and closes)
+with ContainerYardEnv(base_url="http://localhost:8000") as env:
+    result = env.reset()
+    print(f"Reset: {result.observation.echoed_message}")
+    # Multiple steps with low latency
+    for msg in ["Hello", "World", "!"]:
+        result = env.step(ContainerYardAction(message=msg))
+        print(f"Echoed: {result.observation.echoed_message}")
+```
+
+The client uses WebSocket connections for:
+- **Lower latency**: No HTTP connection overhead per request
+- **Persistent session**: Server maintains your environment state
+- **Efficient for episodes**: Better for many sequential steps
+
+### Concurrent WebSocket Sessions
+
+The server supports multiple concurrent WebSocket connections. To enable this,
+modify `server/app.py` to use factory mode:
+
+```python
+# In server/app.py - use factory mode for concurrent sessions
+app = create_app(
+    ContainerYardEnvironment,  # Pass class, not instance
+    ContainerYardAction,
+    ContainerYardObservation,
+    max_concurrent_envs=4,  # Allow 4 concurrent sessions
+)
+```
+
+Then multiple clients can connect simultaneously:
+
+```python
+from Container_Yard import ContainerYardAction, ContainerYardEnv
+from concurrent.futures import ThreadPoolExecutor
+
+def run_episode(client_id: int):
+    with ContainerYardEnv(base_url="http://localhost:8000") as env:
+        result = env.reset()
+        for i in range(10):
+            result = env.step(ContainerYardAction(message=f"Client {client_id}, step {i}"))
+        return client_id, result.observation.message_length
+
+# Run 4 episodes concurrently
+with ThreadPoolExecutor(max_workers=4) as executor:
+    results = list(executor.map(run_episode, range(4)))
+```
+
+## Development & Testing
+
+### Direct Environment Testing
+
+Test the environment logic directly without starting the HTTP server:
+
+```bash
+# From the server directory
+python3 server/Container_Yard_environment.py
+```
+
+This verifies that:
+- Environment resets correctly
+- Step executes actions properly
+- State tracking works
+- Rewards are calculated correctly
+
+### Running Locally
+
+Run the server locally for development:
+
+```bash
+uvicorn server.app:app --reload
+```
+
+## Project Structure
+
+```
+Container_Yard/
+├── .dockerignore         # Docker build exclusions
+├── __init__.py            # Module exports
+├── README.md              # This file
+├── openenv.yaml           # OpenEnv manifest
+├── pyproject.toml         # Project metadata and dependencies
+├── uv.lock                # Locked dependencies (generated)
+├── client.py              # ContainerYardEnv client
+├── models.py              # Action and Observation models
+└── server/
+    ├── __init__.py        # Server module exports
+    ├── Container_Yard_environment.py  # Core environment logic
+    ├── app.py             # FastAPI application (HTTP + WebSocket endpoints)
+    └── Dockerfile         # Container image definition
+```

__init__.py

@@ -0,0 +1,16 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Container Yard Environment."""
+
+from .client import ContainerYardEnv
+from .models import ContainerYardAction, ContainerYardObservation
+
+__all__ = [
+    "ContainerYardAction",
+    "ContainerYardObservation",
+    "ContainerYardEnv",
+]

client.py

@@ -0,0 +1,105 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Container Yard Environment Client."""
+
+from typing import Dict
+
+from openenv.core import EnvClient
+from openenv.core.client_types import StepResult
+from openenv.core.env_server.types import State
+
+from .models import ContainerYardAction, ContainerYardObservation
+
+
+class ContainerYardEnv(
+    EnvClient[ContainerYardAction, ContainerYardObservation, State]
+):
+    """
+    Client for the Container Yard Environment.
+
+    This client maintains a persistent WebSocket connection to the environment server,
+    enabling efficient multi-step interactions with lower latency.
+    Each client instance has its own dedicated environment session on the server.
+
+    Example:
+        >>> # Connect to a running server
+        >>> with ContainerYardEnv(base_url="http://localhost:8000") as client:
+        ...     result = client.reset()
+        ...     print(result.observation.echoed_message)
+        ...
+        ...     result = client.step(ContainerYardAction(message="Hello!"))
+        ...     print(result.observation.echoed_message)
+
+    Example with Docker:
+        >>> # Automatically start container and connect
+        >>> client = ContainerYardEnv.from_docker_image("Container_Yard-env:latest")
+        >>> try:
+        ...     result = client.reset()
+        ...     result = client.step(ContainerYardAction(message="Test"))
+        ... finally:
+        ...     client.close()
+    """
+
+    def _step_payload(self, action: ContainerYardAction) -> Dict:
+        """
+        Convert ContainerYardAction to JSON payload for step message.
+
+        Args:
+            action: ContainerYardAction instance
+
+        Returns:
+            Dictionary representation suitable for JSON encoding
+        """
+        return {
+            "stack_index": action.stack_index,
+        }
+
+    def _parse_result(self, payload: Dict) -> StepResult[ContainerYardObservation]:
+        """
+        Parse server response into StepResult[ContainerYardObservation].
+
+        Args:
+            payload: JSON response data from server
+
+        Returns:
+            StepResult with ContainerYardObservation
+        """
+        obs_data = payload.get("observation", {})
+        observation = ContainerYardObservation(
+            stacks=obs_data.get("stacks", []),
+            containers_placed=obs_data.get("containers_placed", 0),
+            total_containers=obs_data.get("total_containers", 0),
+            current_container_id=obs_data.get("current_container_id", -1),
+            current_container_priority=obs_data.get("current_container_priority", 0),
+            rehandles_so_far=obs_data.get("rehandles_so_far", 0),
+            num_stacks=obs_data.get("num_stacks", 10),
+            max_stack_height=obs_data.get("max_stack_height", 5),
+            action_error=obs_data.get("action_error"),
+            done=payload.get("done", False),
+            reward=payload.get("reward", 0.0),
+        )
+
+        return StepResult(
+            observation=observation,
+            reward=payload.get("reward", 0.0),
+            done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: Dict) -> State:
+        """
+        Parse server response into State object.
+
+        Args:
+            payload: JSON response from state request
+
+        Returns:
+            State object with episode_id and step_count
+        """
+        return State(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+        )

inference.py

@@ -0,0 +1,214 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Inference script for Container Yard environment using OpenAI API.
+
+This script evaluates a language model's ability to solve container yard placement
+tasks using the hackathon-specified output format.
+"""
+
+import os
+import sys
+import json
+from typing import Optional
+
+# Load environment variables from .env file if it exists
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:
+    pass  # python-dotenv not installed, use system env vars
+
+from openai import OpenAI
+
+# Read environment variables with defaults
+API_BASE_URL = os.getenv("API_BASE_URL", "https://api.openai.com/v1")
+MODEL_NAME = os.getenv("MODEL_NAME", "gpt-4o-mini")
+HF_TOKEN = os.getenv("HF_TOKEN")
+
+if HF_TOKEN is None:
+    raise ValueError("HF_TOKEN environment variable is required")
+
+# Initialize OpenAI client
+client = OpenAI(
+    base_url=API_BASE_URL,
+    api_key=HF_TOKEN
+)
+
+# Import environment
+from server.Container_Yard_environment import ContainerYardEnvironment
+from models import ContainerYardAction
+
+
+def extract_stack_choice(response: str, num_stacks: int) -> Optional[int]:
+    """
+    Extract stack choice from LLM response.
+    
+    Looks for patterns like "stack 0", "stack=3", or just a number.
+    Returns None if extraction fails.
+    """
+    response_lower = response.lower().strip()
+    
+    # Try pattern: "stack X"
+    words = response_lower.split()
+    for i, word in enumerate(words):
+        if "stack" in word and i + 1 < len(words):
+            try:
+                stack_idx = int(words[i + 1])
+                if 0 <= stack_idx < num_stacks:
+                    return stack_idx
+            except ValueError:
+                pass
+    
+    # Try extracting any number
+    import re
+    numbers = re.findall(r'\d+', response_lower)
+    if numbers:
+        try:
+            stack_idx = int(numbers[0])
+            if 0 <= stack_idx < num_stacks:
+                return stack_idx
+        except (ValueError, IndexError):
+            pass
+    
+    return None
+
+
+def run_task(task_name: str = "medium") -> dict:
+    """
+    Run a single task in the Container Yard environment.
+    
+    Args:
+        task_name: "easy", "medium", or "hard"
+        
+    Returns:
+        dict with episode results
+    """
+    env = ContainerYardEnvironment(task_name=task_name)
+    obs = env.reset()
+
+    print(f"[START] task={task_name} env=container-yard model={MODEL_NAME}")
+    sys.stdout.flush()
+
+    step_count = 0
+    all_rewards = []
+    success = False
+    last_error = None
+    efficiency_score = 0.0
+    
+    try:
+        while not obs.done and step_count < 100:
+            step_count += 1
+
+            prompt = f"""You are managing a container yard. 
+
+Current state:
+- Container to place: ID={obs.current_container_id}, Priority={obs.current_container_priority}
+- Available stacks: {obs.num_stacks} stacks (0-{obs.num_stacks-1})
+- Max stack height: {obs.max_stack_height}
+- Current stacks: {json.dumps(obs.stacks)}
+- Rehandles so far: {obs.rehandles_so_far}
+
+Place the container in the stack that minimizes future rehandles.
+Reply with ONLY the stack number (0-{obs.num_stacks-1}). No explanation needed."""
+
+            try:
+                response = client.chat.completions.create(
+                    model=MODEL_NAME,
+                    messages=[{"role": "user", "content": prompt}],
+                    temperature=0.7,
+                    max_tokens=10,
+                )
+                action_str = (response.choices[0].message.content or "").strip()
+            except Exception as e:
+                action_str = "0"
+                last_error = str(e)
+
+            stack_idx = extract_stack_choice(action_str, obs.num_stacks)
+            if stack_idx is None:
+                stack_idx = 0
+
+            try:
+                action = ContainerYardAction(stack_index=stack_idx)
+                obs = env.step(action)
+
+                reward_value = float(obs.reward or 0.0)
+                all_rewards.append(reward_value)
+
+                error_msg = obs.action_error if obs.action_error else "null"
+                print(
+                    f"[STEP] step={step_count} action=place({stack_idx}) "
+                    f"reward={reward_value:.2f} done={str(obs.done).lower()} error={error_msg}"
+                )
+                sys.stdout.flush()
+
+                if obs.done:
+                    success = True
+                    break
+
+            except Exception as e:
+                last_error = str(e)
+                print(f"[STEP] step={step_count} action=place({stack_idx}) reward=0.00 done=true error={last_error}")
+                sys.stdout.flush()
+                break
+
+        if step_count > 0:
+            efficiency_score = 1.0 - (obs.rehandles_so_far / max(obs.total_containers, 1))
+            success = success and step_count == obs.total_containers
+
+    except Exception as e:
+        last_error = str(e)
+
+    finally:
+        close_fn = getattr(env, "close", None)
+        if callable(close_fn):
+            try:
+                close_fn()
+            except Exception:
+                pass
+
+        rewards_str = ",".join([f"{r:.2f}" for r in all_rewards])
+        print(f"[END] success={str(success).lower()} steps={step_count} rewards={rewards_str}")
+        sys.stdout.flush()
+    
+    return {
+        "task": task_name,
+        "success": success,
+        "steps": step_count,
+        "total_rewards": sum(all_rewards),
+        "rehandles": obs.rehandles_so_far,
+        "efficiency": efficiency_score,
+    }
+
+
+def main():
+    """Run all three tasks."""
+    tasks = ["easy", "medium", "hard"]
+    results = []
+    
+    for task in tasks:
+        try:
+            result = run_task(task)
+            results.append(result)
+        except Exception as e:
+            print(f"[ERROR] Task {task} failed: {e}", file=sys.stderr)
+            results.append({
+                "task": task,
+                "success": False,
+                "steps": 0,
+                "total_rewards": 0.0,
+                "error": str(e),
+            })
+    
+    # Summary
+    print("\n=== Summary ===", file=sys.stderr)
+    for result in results:
+        print(f"Task {result['task']}: success={result['success']}, efficiency={result.get('efficiency', 0.0):.2f}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

models.py

@@ -0,0 +1,52 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Data models for the Container Yard Environment.
+
+The Container Yard environment simulates a port container yard where containers
+arrive sequentially and must be placed into stacks to minimize rehandles during
+retrieval operations.
+"""
+
+from typing import List, Optional
+from openenv.core.env_server.types import Action, Observation
+from pydantic import Field
+
+
+class Container:
+    """Represents a single container with ID and priority."""
+    
+    def __init__(self, container_id: int, priority: int):
+        self.container_id = container_id
+        priority_map = {1: 0, 2: 1, 3: 2}  # 1=earliest (0), 3=latest (2)
+        self.retrieval_priority = priority_map.get(priority, 0)
+    
+    def __repr__(self):
+        return f"C{self.container_id}(P{self.retrieval_priority})"
+
+
+class ContainerYardAction(Action):
+    """Action to place a container in a specific stack."""
+    
+    stack_index: int = Field(..., description="Index of the stack to place container in (0-9)")
+    
+
+class ContainerYardObservation(Observation):
+    """Observation of the current container yard state."""
+    
+    stacks: List[List[int]] = Field(
+        default_factory=list,
+        description="Current state of stacks (container IDs, -1 means empty slot)"
+    )
+    containers_placed: int = Field(default=0, description="Number of containers placed so far")
+    total_containers: int = Field(default=0, description="Total containers in this episode")
+    current_container_id: int = Field(default=-1, description="ID of current container to place (-1 if done)")
+    current_container_priority: int = Field(default=0, description="Priority of current container (1-3)")
+    rehandles_so_far: int = Field(default=0, description="Total rehandles occurred so far")
+    num_stacks: int = Field(default=10, description="Number of stacks in the yard")
+    max_stack_height: int = Field(default=5, description="Maximum height of each stack")
+    action_error: Optional[str] = Field(default=None, description="Error message if last action failed")

openenv.yaml

@@ -0,0 +1,20 @@
+spec_version: 1
+name: Container_Yard
+type: space
+runtime: fastapi
+app: server.app:app
+port: 8000
+description: |
+  Container Yard Port Operations Simulation
+  Simulates a real-world port container yard where agents must place arriving containers
+  into stacks to minimize rehandles during retrieval operations.
+metadata:
+  difficulty_levels:
+    - easy
+    - medium
+    - hard
+  tasks: 3
+  observation_space: Stack states with container priorities
+  action_space: Discrete(10) - stack selection
+  reward: Incremental feedback based on placement efficiency
+  max_container_height: 3-5 (task dependent)

pyproject.toml

@@ -0,0 +1,39 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-Container_Yard"
+version = "0.1.0"
+description = "Container Yard environment for OpenEnv - port container yard simulation"
+requires-python = ">=3.10"
+dependencies = [
+    # Core OpenEnv runtime
+    "openenv-core[core]>=0.2.2",
+    # LLM inference
+    "openai>=1.0.0",
+    # Additional dependencies
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.scripts]
+# Server entry point - enables running via: uv run --project . server
+# or: python -m Container_Yard.server.app
+server = "Container_Yard.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["Container_Yard", "Container_Yard.server"]
+package-dir = { "Container_Yard" = ".", "Container_Yard.server" = "server" }

quickstart.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+# Quick start guide for Container Yard Environment
+
+echo "Container Yard Environment - Quick Start"
+echo "=========================================="
+echo ""
+
+# Check if HF_TOKEN is set
+if [ -z "$HF_TOKEN" ]; then
+    echo "⚠️  HF_TOKEN not set! This is required for inference.py"
+    echo ""
+    echo "Set it with:"
+    echo "  export HF_TOKEN='your-hugging-face-token'"
+    echo ""
+else
+    echo "✓ HF_TOKEN is set"
+fi
+
+# Show environment variable options
+echo ""
+echo "Optional environment variables:"
+echo "  API_BASE_URL (default: https://api.openai.com/v1)"
+echo "  MODEL_NAME (default: gpt-4o-mini)"
+echo ""
+
+# Test local environment
+echo "Testing local environment..."
+python -c "
+import sys
+sys.path.insert(0, '.')
+
+try:
+    from server.Container_Yard_environment import ContainerYardEnvironment
+    from models import ContainerYardAction
+    print('✓ Environment imports OK')
+except Exception as e:
+    print(f'✗ Import error: {e}')
+    sys.exit(1)
+
+# Quick environment test
+env = ContainerYardEnvironment('easy')
+obs = env.reset()
+print(f'✓ Environment reset OK ({obs.total_containers} containers)')
+" && echo "" && echo "✓ Ready to run inference!" || echo "✗ Setup failed"
+
+echo ""
+echo "To run inference:"
+echo "  python inference.py"
+echo ""
+echo "To test Docker build:"
+echo "  docker build -t container-yard ."
+echo "  docker run -p 8000:8000 container-yard"

server/Container_Yard_environment.py

@@ -0,0 +1,222 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Container Yard Environment Implementation.
+
+Simulates a port container yard where containers arrive sequentially with different
+retrieval priorities (1-3). The objective is to place containers into stacks to
+minimize rehandles during retrieval operations.
+"""
+
+from uuid import uuid4
+from typing import List, Tuple
+import random
+
+from openenv.core.env_server.interfaces import Environment
+from openenv.core.env_server.types import State
+
+try:
+    from ..models import ContainerYardAction, ContainerYardObservation, Container
+except ImportError:
+    from models import ContainerYardAction, ContainerYardObservation, Container
+
+
+class ContainerYardEnvironment(Environment):
+    """
+    Container Yard environment for the hackathon challenge.
+    
+    Containers arrive with priorities 1-3 (1=earliest retrieval, 3=latest).
+    Each stack can hold up to max_stack_height containers.
+    Agents must place containers to minimize rehandles during retrieval.
+    """
+
+    SUPPORTS_CONCURRENT_SESSIONS: bool = True
+
+    def __init__(self, task_name: str = "medium"):
+        """
+        Initialize the Container Yard environment.
+        
+        Args:
+            task_name: "easy" (5 containers, all priority 1), 
+                      "medium" (10 containers, priority 1-2),
+                      "hard" (15 containers, priority 1-3)
+        """
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self.task_name = task_name
+        self._setup_task(task_name)
+        
+        # Environment state
+        self.containers: List[Container] = []
+        self.stacks: List[List[int]] = [[] for _ in range(self.num_stacks)]
+        self.current_container_idx = 0
+        self.rehandles = 0
+        self.placement_history: List[Tuple[int, int]] = []  # (container_id, stack_idx)
+        
+    def _setup_task(self, task_name: str):
+        """Configure environment parameters based on task difficulty."""
+        tasks = {
+            "easy": {"num_containers": 5, "num_stacks": 5, "max_height": 5, "priorities": [1, 1, 1, 1, 1]},
+            "medium": {"num_containers": 10, "num_stacks": 8, "max_height": 4, 
+                      "priorities": [1, 1, 1, 1, 2, 2, 2, 1, 2, 1]},
+            "hard": {"num_containers": 15, "num_stacks": 10, "max_height": 3,
+                    "priorities": [1, 2, 1, 3, 2, 1, 3, 2, 1, 2, 3, 1, 2, 3, 1]},
+        }
+        
+        config = tasks.get(task_name, tasks["medium"])
+        self.num_containers = config["num_containers"]
+        self.num_stacks = config["num_stacks"]
+        self.max_stack_height = config["max_height"]
+        self.priorities = config["priorities"]
+
+    def reset(self) -> ContainerYardObservation:
+        """
+        Reset the environment for a new episode.
+        
+        Returns:
+            Initial observation
+        """
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        
+        # Initialize containers with priorities
+        self.containers = [
+            Container(i, self.priorities[i]) for i in range(self.num_containers)
+        ]
+        
+        # Shuffle container arrival order
+        random.shuffle(self.containers)
+        
+        self.stacks = [[] for _ in range(self.num_stacks)]
+        self.current_container_idx = 0
+        self.rehandles = 0
+        self.placement_history = []
+        
+        return self._get_observation(action_error=None)
+
+    def step(self, action: ContainerYardAction) -> ContainerYardObservation:
+        """
+        Execute one step: place current container in specified stack.
+        
+        Args:
+            action: ContainerYardAction with stack_index
+            
+        Returns:
+            ContainerYardObservation with updated yard state
+        """
+        self._state.step_count += 1
+        error = None
+        
+        stack_idx = action.stack_index
+        
+        # Validate action
+        if stack_idx < 0 or stack_idx >= self.num_stacks:
+            error = f"Invalid stack index {stack_idx}. Valid range: 0-{self.num_stacks-1}"
+            return self._get_observation(action_error=error)
+        
+        if len(self.stacks[stack_idx]) >= self.max_stack_height:
+            error = f"Stack {stack_idx} is full (height={len(self.stacks[stack_idx])})"
+            return self._get_observation(action_error=error)
+        
+        # Place container
+        container = self.containers[self.current_container_idx]
+        self.stacks[stack_idx].append(container.container_id)
+        self.placement_history.append((container.container_id, stack_idx))
+        
+        # Check for rehandles caused by this placement
+        rehandles_caused = self._count_rehandles_from_placement(stack_idx, container)
+        self.rehandles += rehandles_caused
+        
+        self.current_container_idx += 1
+        done = (self.current_container_idx >= self.num_containers)
+        
+        # Compute reward
+        reward = self._compute_reward(container, stack_idx, rehandles_caused)
+        
+        obs = self._get_observation(action_error=error)
+        obs.reward = reward
+        obs.done = done
+        
+        return obs
+
+    def _count_rehandles_from_placement(self, stack_idx: int, container: Container) -> int:
+        """
+        Count how many containers in this stack would need to be rehandled
+        because this container is placed on top of them.
+        
+        Rehandle: container X is in stack with container Y below it,
+        but X has LOWER priority (earlier retrieval) than Y.
+        """
+        rehandles = 0
+        stack = self.stacks[stack_idx]
+        
+        if len(stack) < 2:
+            return rehandles
+        
+        # Check all containers below the newly placed one
+        newly_placed_priority = container.retrieval_priority
+        for i in range(len(stack) - 1):
+            below_id = stack[i]
+            # Find the container with this ID to get its priority
+            below_container = next(c for c in self.containers if c.container_id == below_id)
+            if below_container.retrieval_priority > newly_placed_priority:
+                rehandles += 1
+        
+        return rehandles
+
+    def _compute_reward(self, container: Container, stack_idx: int, rehandles_caused: int) -> float:
+        """Compute reward for placing a container."""
+        reward = 0.0
+        
+        # Base reward: successful placement
+        reward += 0.1
+        
+        # Penalty for rehandles
+        reward -= rehandles_caused * 0.5
+        
+        # Bonus for efficient placement
+        if rehandles_caused == 0:
+            reward += 0.3
+        
+        # Bonus for stacking containers with same priority
+        stack = self.stacks[stack_idx]
+        if len(stack) > 1:
+            below_id = stack[-2]
+            below_container = next(c for c in self.containers if c.container_id == below_id)
+            if below_container.retrieval_priority == container.retrieval_priority:
+                reward += 0.2
+        
+        return reward
+
+    def _get_observation(self, action_error: str = None) -> ContainerYardObservation:
+        """Build observation from current state."""
+        current_id = -1
+        current_priority = 0
+        
+        if self.current_container_idx < len(self.containers):
+            current_id = self.containers[self.current_container_idx].container_id
+            current_priority = self.containers[self.current_container_idx].retrieval_priority + 1
+        
+        # Stacks already contain container IDs directly
+        stacks_data = [list(stack) for stack in self.stacks]
+        
+        return ContainerYardObservation(
+            stacks=stacks_data,
+            containers_placed=self.current_container_idx,
+            total_containers=self.num_containers,
+            current_container_id=current_id,
+            current_container_priority=current_priority,
+            rehandles_so_far=self.rehandles,
+            num_stacks=self.num_stacks,
+            max_stack_height=self.max_stack_height,
+            action_error=action_error,
+            done=(self.current_container_idx >= self.num_containers),
+            reward=0.0,
+        )
+
+    @property
+    def state(self) -> State:
+        """Get current environment state."""
+        return self._state

server/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Container Yard environment server components."""
+
+from .Container_Yard_environment import ContainerYardEnvironment
+
+__all__ = ["ContainerYardEnvironment"]

server/app.py

@@ -0,0 +1,84 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+FastAPI application for the Container Yard Environment.
+
+This module creates an HTTP server that exposes the ContainerYardEnvironment
+over HTTP and WebSocket endpoints, compatible with EnvClient.
+
+Endpoints:
+    - POST /reset: Reset the environment
+    - POST /step: Execute an action
+    - GET /state: Get current environment state
+    - GET /schema: Get action/observation schemas
+    - WS /ws: WebSocket endpoint for persistent sessions
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000 --workers 4
+
+    # Or run directly:
+    python -m server.app
+"""
+
+try:
+    from openenv.core.env_server.http_server import create_app
+except Exception as e:  # pragma: no cover
+    raise ImportError(
+        "openenv is required for the web interface. Install dependencies with '\n    uv sync\n'"
+    ) from e
+
+try:
+    from ..models import ContainerYardAction, ContainerYardObservation
+    from .Container_Yard_environment import ContainerYardEnvironment
+except ModuleNotFoundError:
+    from models import ContainerYardAction, ContainerYardObservation
+    from server.Container_Yard_environment import ContainerYardEnvironment
+
+
+# Create the app with web interface and README integration
+app = create_app(
+    ContainerYardEnvironment,
+    ContainerYardAction,
+    ContainerYardObservation,
+    env_name="Container_Yard",
+    max_concurrent_envs=1,  # increase this number to allow more concurrent WebSocket sessions
+)
+
+
+def main(host: str = "0.0.0.0", port: int = 8000):
+    """
+    Entry point for direct execution via uv run or python -m.
+
+    This function enables running the server without Docker:
+        uv run --project . server
+        uv run --project . server --port 8001
+        python -m Container_Yard.server.app
+
+    Args:
+        host: Host address to bind to (default: "0.0.0.0")
+        port: Port number to listen on (default: 8000)
+
+    For production deployments, consider using uvicorn directly with
+    multiple workers:
+        uvicorn Container_Yard.server.app:app --workers 4
+    """
+    import uvicorn
+
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--port", type=int, default=8000)
+    args = parser.parse_args()
+    main(port=args.port)

server/requirements.txt

@@ -0,0 +1,6 @@
+openenv[core]>=0.2.0
+fastapi>=0.115.0
+uvicorn>=0.24.0
+
+
+

test_env.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""
+Simple test script to validate the Container Yard environment locally.
+This doesn't require OpenAI API or a running server.
+"""
+
+import sys
+sys.path.insert(0, '.')
+
+from server.Container_Yard_environment import ContainerYardEnvironment
+from models import ContainerYardAction
+
+def test_task(task_name: str, num_steps: int = 100):
+    """Test a single task."""
+    print(f"\n{'='*60}")
+    print(f"Testing {task_name.upper()} task")
+    print(f"{'='*60}")
+    
+    env = ContainerYardEnvironment(task_name=task_name)
+    obs = env.reset()
+    
+    print(f"Initial state:")
+    print(f"  - Containers: {obs.total_containers}")
+    print(f"  - Stacks: {obs.num_stacks}")
+    print(f"  - Max height: {obs.max_stack_height}")
+    
+    step_count = 0
+    total_reward = 0.0
+    
+    while not obs.done and step_count < num_steps:
+        step_count += 1
+        
+        # Simple greedy strategy: place in stack with fewest containers
+        stack_sizes = [len(stack) for stack in obs.stacks]
+        best_stack = min(range(len(stack_sizes)), key=lambda i: stack_sizes[i])
+        
+        action = ContainerYardAction(stack_index=best_stack)
+        obs = env.step(action)
+        total_reward += obs.reward
+        
+        if step_count <= 3 or obs.done:
+            print(f"Step {step_count}: Placed C{obs.current_container_id-1 if obs.current_container_id > 0 else 'X'} "
+                  f"in stack {best_stack}, reward={obs.reward:.2f}, "
+                  f"rehandles={obs.rehandles_so_far}")
+    
+    efficiency = 1.0 - (obs.rehandles_so_far / obs.total_containers)
+    
+    print(f"\nFinal results:")
+    print(f"  - Steps taken: {step_count}")
+    print(f"  - Total reward: {total_reward:.2f}")
+    print(f"  - Total rehandles: {obs.rehandles_so_far}")
+    print(f"  - Efficiency score: {efficiency:.2f}")
+    print(f"  - Success: {obs.rehandles_so_far <= 3 * (len(obs.stacks) // 5)}")
+    
+    return {
+        'task': task_name,
+        'steps': step_count,
+        'rehandles': obs.rehandles_so_far,
+        'efficiency': efficiency,
+        'total_reward': total_reward,
+    }
+
+if __name__ == "__main__":
+    print("Container Yard Environment - Local Test")
+    
+    results = []
+    for task in ['easy', 'medium', 'hard']:
+        try:
+            result = test_task(task)
+            results.append(result)
+        except Exception as e:
+            print(f"ERROR in {task} task: {e}")
+            import traceback
+            traceback.print_exc()
+    
+    print(f"\n{'='*60}")
+    print("Summary")
+    print(f"{'='*60}")
+    for r in results:
+        print(f"{r['task']:8} | Steps: {r['steps']:2} | Rehandles: {r['rehandles']:2} | Efficiency: {r['efficiency']:.2f}")