Upload folder using huggingface_hub

Dockerfile

@@ -0,0 +1,7 @@
+FROM python:3.11-slim
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY . .
+ENV ENABLE_WEB_INTERFACE=true
+CMD ["uvicorn", "server.app:app", "--host", "0.0.0.0", "--port", "8000"]

README.md

@@ -1,10 +1,255 @@
 ---
-title: Support Env
-emoji: 😻
-colorFrom: gray
-colorTo: purple
+title: Support Env Environment Server
+emoji: 🔔
+colorFrom: yellow
+colorTo: gray
 sdk: docker
 pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Support Env Environment
+
+A simple test environment that echoes back messages. Perfect for testing the env APIs as well as demonstrating environment usage patterns.
+
+## Quick Start
+
+The simplest way to use the Support Env environment is through the `SupportEnv` class:
+
+```python
+from support_env import SupportAction, SupportEnv
+
+try:
+    # Create environment from Docker image
+    support_envenv = SupportEnv.from_docker_image("support_env-env:latest")
+
+    # Reset
+    result = support_envenv.reset()
+    print(f"Reset: {result.observation.echoed_message}")
+
+    # Send multiple messages
+    messages = ["Hello, World!", "Testing echo", "Final message"]
+
+    for msg in messages:
+        result = support_envenv.step(SupportAction(message=msg))
+        print(f"Sent: '{msg}'")
+        print(f"  → Echoed: '{result.observation.echoed_message}'")
+        print(f"  → Length: {result.observation.message_length}")
+        print(f"  → Reward: {result.reward}")
+
+finally:
+    # Always clean up
+    support_envenv.close()
+```
+
+That's it! The `SupportEnv.from_docker_image()` method handles:
+- Starting the Docker container
+- Waiting for the server to be ready
+- 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 support_env-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
+**SupportAction**: Contains a single field
+- `message` (str) - The message to echo back
+
+### Observation
+**SupportObservation**: 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 Support Env environment server running, you can connect directly:
+
+```python
+from support_env import SupportEnv
+
+# Connect to existing server
+support_envenv = SupportEnv(base_url="<ENV_HTTP_URL_HERE>")
+
+# Use as normal
+result = support_envenv.reset()
+result = support_envenv.step(SupportAction(message="Hello!"))
+```
+
+Note: When connecting to an existing server, `support_envenv.close()` will NOT stop the server.
+
+### Using the Context Manager
+
+The client supports context manager usage for automatic connection management:
+
+```python
+from support_env import SupportAction, SupportEnv
+
+# Connect with context manager (auto-connects and closes)
+with SupportEnv(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(SupportAction(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(
+    SupportEnvironment,  # Pass class, not instance
+    SupportAction,
+    SupportObservation,
+    max_concurrent_envs=4,  # Allow 4 concurrent sessions
+)
+```
+
+Then multiple clients can connect simultaneously:
+
+```python
+from support_env import SupportAction, SupportEnv
+from concurrent.futures import ThreadPoolExecutor
+
+def run_episode(client_id: int):
+    with SupportEnv(base_url="http://localhost:8000") as env:
+        result = env.reset()
+        for i in range(10):
+            result = env.step(SupportAction(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/support_env_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
+
+```
+support_env/
+├── .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              # SupportEnv client
+├── models.py              # Action and Observation models
+└── server/
+    ├── __init__.py        # Server module exports
+    ├── support_env_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.
+
+"""Support Env Environment."""
+
+from .client import SupportEnv
+from .models import SupportAction, SupportObservation
+
+__all__ = [
+    "SupportAction",
+    "SupportObservation",
+    "SupportEnv",
+]

client.py

@@ -0,0 +1,21 @@
+from openenv.core.env_client import EnvClient
+from openenv.core.client_types import StepResult
+from .models import SupportAction, SupportObservation, SupportState
+
+class SupportEnvClient(EnvClient[SupportAction, SupportObservation, SupportState]):
+    def _step_payload(self, action: SupportAction) -> dict:
+        return {"department": action.department}
+
+    def _parse_result(self, payload: dict) -> StepResult:
+        obs = payload.get("observation", {})
+        return StepResult(
+            observation=SupportObservation(
+                done=payload.get("done", False), reward=payload.get("reward", 0.0),
+                ticket_id=obs.get("ticket_id", ""), ticket_text=obs.get("ticket_text", ""),
+                message=obs.get("message", "")
+            ),
+            reward=payload.get("reward", 0.0), done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: dict) -> SupportState:
+        return SupportState(**payload)

inference.py

@@ -0,0 +1,51 @@
+import os
+from openai import OpenAI
+from client import SupportEnvClient, SupportAction
+
+API_BASE_URL = os.getenv("API_BASE_URL", "https://router.huggingface.co/v1")
+MODEL_NAME = os.getenv("MODEL_NAME", "Qwen/Qwen2.5-72B-Instruct")
+API_KEY = os.getenv("HF_TOKEN") or os.getenv("API_KEY", "dummy-key")
+BENCHMARK = "support_env"
+
+client = OpenAI(base_url=API_BASE_URL, api_key=API_KEY)
+
+def run_task(task_name: str):
+    env_url = os.getenv("ENV_URL", "http://localhost:8000")
+    env = SupportEnvClient(base_url=env_url).sync()
+    result = env.reset(task_name=task_name)
+    
+    print(f"[START] task={task_name} env={BENCHMARK} model={MODEL_NAME}")
+    
+    step = 1
+    rewards = []
+    
+    while not result.done:
+        prompt = f"Ticket: '{result.observation.ticket_text}'. Reply ONLY with one word: Billing, Tech, or Sales."
+        try:
+            response = client.chat.completions.create(
+                model=MODEL_NAME,
+                messages=[{"role": "user", "content": prompt}],
+                max_tokens=10
+            )
+            action_str = response.choices[0].message.content.strip()
+        except Exception:
+            action_str = "Tech" # Fallback if API fails
+            
+        result = env.step(SupportAction(department=action_str))
+        reward_val = float(result.reward or 0.0)
+        rewards.append(reward_val)
+        
+        done_str = str(result.done).lower()
+        print(f"[STEP] step={step} action={action_str} reward={reward_val:.2f} done={done_str} error=null")
+        step += 1
+
+    score = sum(rewards) / len(rewards) if rewards else 0.0
+    success = str(score > 0).lower()
+    rewards_str = ",".join([f"{r:.2f}" for r in rewards])
+    
+    print(f"[END] success={success} steps={step-1} score={score:.2f} rewards={rewards_str}")
+    env.close()
+
+if __name__ == "__main__":
+    for task in ["easy", "medium", "hard"]:
+        run_task(task)

models.py

@@ -0,0 +1,15 @@
+from typing import List, Optional, Dict
+from openenv.core.env_server import Action, Observation, State
+
+class SupportAction(Action):
+    department: str
+
+class SupportObservation(Observation):
+    ticket_id: str
+    ticket_text: str
+    message: str
+
+class SupportState(State):
+    task_name: str = "easy"
+    total_tickets: int = 1
+    tickets_routed: int = 0

openenv.yaml

@@ -0,0 +1,10 @@
+name: "support_env"
+version: "1.0"
+description: "A real-world environment for routing customer support tickets."
+tasks:
+  - id: "easy"
+    description: "Route 1 obvious ticket."
+  - id: "medium"
+    description: "Route 2 standard tickets."
+  - id: "hard"
+    description: "Route 3 complex tickets."

pyproject.toml

@@ -0,0 +1,45 @@
+# 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-support_env"
+version = "0.1.0"
+description = "Support Env environment for OpenEnv"
+requires-python = ">=3.10"
+dependencies = [
+    # Core OpenEnv runtime (provides FastAPI server + HTTP client types)
+    # install from github
+    # "openenv-core[core] @ git+https://github.com/meta-pytorch/OpenEnv.git",
+    "openenv-core[core]>=0.2.2",
+    # Environment-specific dependencies
+    # Add all dependencies needed for your environment here
+    # Examples:
+    # "numpy>=1.19.0",
+    # "torch>=2.0.0",
+    # "gymnasium>=0.29.0",
+    # "openspiel>=1.0.0",
+    # "smolagents>=1.22.0,<2",
+]
+
+[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 support_env.server.app
+server = "support_env.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["support_env", "support_env.server"]
+package-dir = { "support_env" = ".", "support_env.server" = "server" }

requirements.txt

@@ -0,0 +1,4 @@
+openenv-core
+fastapi
+uvicorn
+pydantic

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.
+
+"""Support Env environment server components."""
+
+from .support_env_environment import SupportEnvironment
+
+__all__ = ["SupportEnvironment"]

server/app.py

@@ -0,0 +1,5 @@
+from openenv.core.env_server import create_fastapi_app
+from ..models import SupportAction, SupportObservation
+from .environment import SupportEnvironment
+
+app = create_fastapi_app(SupportEnvironment, SupportAction, SupportObservation)

server/environment.py

@@ -0,0 +1,54 @@
+import uuid
+from typing import List, Dict
+from openenv.core.env_server import Observation
+from ..models import SupportAction, SupportObservation, SupportState
+
+class SupportEnvironment:
+    def __init__(self):
+        self._state = SupportState()
+        self._current_queue: List[Dict[str, str]] = []
+        self._current_ticket = None
+        self.tasks = {
+            "easy": [{"id": "T1", "text": "Can I get a refund for my last invoice?", "dept": "Billing"}],
+            "medium": [{"id": "T2", "text": "My screen is flickering.", "dept": "Tech"},
+                       {"id": "T3", "text": "I want to upgrade.", "dept": "Sales"}],
+            "hard": [{"id": "T4", "text": "Update credit card?", "dept": "Billing"},
+                     {"id": "T5", "text": "Enterprise discount?", "dept": "Sales"},
+                     {"id": "T6", "text": "API 500 error on POST.", "dept": "Tech"}]
+        }
+
+    def reset(self, task_name: str = "easy") -> SupportObservation:
+        if task_name not in self.tasks:
+            task_name = "easy"
+        self._current_queue = self.tasks[task_name].copy()
+        self._state = SupportState(
+            episode_id=str(uuid.uuid4()), step_count=0, task_name=task_name,
+            total_tickets=len(self._current_queue), tickets_routed=0
+        )
+        self._current_ticket = self._current_queue.pop(0)
+        return SupportObservation(
+            done=False, reward=0.0, ticket_id=self._current_ticket["id"],
+            ticket_text=self._current_ticket["text"], message="Please route this ticket."
+        )
+
+    def step(self, action: SupportAction) -> SupportObservation:
+        self._state.step_count += 1
+        is_correct = action.department.lower() == self._current_ticket["dept"].lower()
+        reward = 1.0 if is_correct else 0.0
+        self._state.tickets_routed += 1
+        
+        if len(self._current_queue) > 0:
+            self._current_ticket = self._current_queue.pop(0)
+            return SupportObservation(
+                done=False, reward=reward, ticket_id=self._current_ticket["id"],
+                ticket_text=self._current_ticket["text"], message=f"Routed. Correct: {is_correct}"
+            )
+        else:
+            return SupportObservation(
+                done=True, reward=reward, ticket_id="None",
+                ticket_text="Queue is empty.", message="All tickets routed."
+            )
+
+    @property
+    def state(self) -> SupportState:
+        return self._state

server/requirements.txt

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

server/support_env_environment.py

@@ -0,0 +1,104 @@
+# 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.
+
+"""
+Support Env Environment Implementation.
+
+A simple test environment that echoes back messages sent to it.
+Perfect for testing HTTP server infrastructure.
+"""
+
+from uuid import uuid4
+
+from openenv.core.env_server.interfaces import Environment
+from openenv.core.env_server.types import State
+
+try:
+    from ..models import SupportAction, SupportObservation
+except ImportError:
+    from models import SupportAction, SupportObservation
+
+
+class SupportEnvironment(Environment):
+    """
+    A simple echo environment that echoes back messages.
+
+    This environment is designed for testing the HTTP server infrastructure.
+    It maintains minimal state and simply echoes back whatever message it receives.
+
+    Example:
+        >>> env = SupportEnvironment()
+        >>> obs = env.reset()
+        >>> print(obs.echoed_message)  # "Support Env environment ready!"
+        >>>
+        >>> obs = env.step(SupportAction(message="Hello"))
+        >>> print(obs.echoed_message)  # "Hello"
+        >>> print(obs.message_length)  # 5
+    """
+
+    # Enable concurrent WebSocket sessions.
+    # Set to True if your environment isolates state between instances.
+    # When True, multiple WebSocket clients can connect simultaneously, each
+    # getting their own environment instance (when using factory mode in app.py).
+    SUPPORTS_CONCURRENT_SESSIONS: bool = True
+
+    def __init__(self):
+        """Initialize the support_env environment."""
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count = 0
+
+    def reset(self) -> SupportObservation:
+        """
+        Reset the environment.
+
+        Returns:
+            SupportObservation with a ready message
+        """
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count += 1
+
+        return SupportObservation(
+            echoed_message="Support Env environment ready!",
+            message_length=0,
+            done=False,
+            reward=0.0,
+        )
+
+    def step(self, action: SupportAction) -> SupportObservation:  # type: ignore[override]
+        """
+        Execute a step in the environment by echoing the message.
+
+        Args:
+            action: SupportAction containing the message to echo
+
+        Returns:
+            SupportObservation with the echoed message and its length
+        """
+        self._state.step_count += 1
+
+        message = action.message
+        length = len(message)
+
+        # Simple reward: longer messages get higher rewards
+        reward = length * 0.1
+
+        return SupportObservation(
+            echoed_message=message,
+            message_length=length,
+            done=False,
+            reward=reward,
+            metadata={"original_message": message, "step": self._state.step_count},
+        )
+
+    @property
+    def state(self) -> State:
+        """
+        Get the current environment state.
+
+        Returns:
+            Current State with episode_id and step_count
+        """
+        return self._state