Initialize GPUClusterEnv boilerplate as per OpenEnv requirements

.github/workflows/sync_to_hub.yml

@@ -0,0 +1,23 @@
+name: Sync to Hugging Face Hub
+
+on:
+  push:
+    branches: [main]
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+jobs:
+  sync-to-hub:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+          lfs: true
+
+      - name: Push to Hugging Face Hub
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          git remote add space https://hiitsesh:$HF_TOKEN@huggingface.co/spaces/hiitsesh/openenv-hackathon
+          git push --force space main

.gitignore

@@ -0,0 +1,5 @@
+venv/
+.env
+.vscode/
+__pycache__/
+.git.old/

Dockerfile

@@ -0,0 +1,11 @@
+FROM python:3.10-slim
+
+WORKDIR /app
+COPY . /app
+
+RUN pip install --no-cache-dir fastapi uvicorn pydantic numpy requests
+
+# Expose port for HF Spaces
+EXPOSE 7860
+
+CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,86 @@
+---
+title: GPUClusterEnv
+emoji: 🚀
+colorFrom: blue
+colorTo: green
+sdk: docker
+pinned: false
+---
+
+# GPU Cluster Resource Management Environment (GPUClusterEnv)
+
+A real-world cloud infrastructure environment where agents manage GPU provisioning to handle ML training workloads under strict budget constraints. 
+
+Managing compute resources for incoming ML training jobs requires balancing strict budgets against Service Level Agreement (SLA) penalties for long queue times. This environment challenges agents to dynamically scale GPU resources to match fluctuating job arrival rates while maximizing overall reward.
+
+## 🚀 Getting Started
+
+### Installation
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/yourusername/GPUClusterEnv
+   cd GPUClusterEnv
+   ```
+
+2. Install dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. Run the FastAPI server:
+   ```bash
+   uvicorn src.main:app --host 0.0.0.0 --port 7860
+   ```
+
+## 🧠 Environment Design
+
+### Observation Space
+
+The observation space is represented as a structured dictionary containing the current state of the GPU cluster:
+
+| Feature | Description | Type |
+| :--- | :--- | :--- |
+| `time_step` | Current step in the episode. | `int` |
+| `active_gpus` | Number of currently provisioned GPUs. | `int` |
+| `queue_size` | Number of jobs waiting to be processed. | `int` |
+| `current_budget` | Remaining budget for the episode. | `float` |
+| `incoming_jobs` | Number of new jobs that arrived in the last step. | `int` |
+
+### Action Space
+
+The agent controls the scaling of the infrastructure by specifying how many GPUs to provision or de-provision:
+
+| Feature | Description | Type | Notes |
+| :--- | :--- | :--- | :--- |
+| `gpus_to_provision` | Number of GPUs to spin up (positive) or spin down (negative). | `int` | Infrastructure scaling |
+
+### Reward Function
+
+Instead of a sparse reward, the environment uses a shaped reward function that continuously evaluates the agent's performance based on processing jobs while minimizing costs and SLA penalties:
+
+$$Reward = (JobsProcessed \times 5.0) - (ActiveGPUs \times CostPerGPU) - (QueueSize \times Penalty)$$
+
+*   **CostPerGPU**: $2.50 per step per active GPU.
+*   **Penalty**: $1.00 SLA penalty per step for each waiting job in the queue.
+
+### Terminal Conditions
+
+An episode ends when:
+1. The maximum number of `time_steps` for the task is reached.
+2. The `current_budget` drops to $0 or below.
+
+## 📋 Tasks
+
+The environment provides 3 graded tasks with escalating difficulty:
+
+1. **Easy** (`task_id: "easy"`): Low job arrival rate, generous budget. (Max Steps: 50)
+2. **Medium** (`task_id: "medium"`): Moderate job arrival rate, standard budget. (Max Steps: 100)
+3. **Hard** (`task_id: "hard"`): High, erratic job arrival rate, tight budget. (Max Steps: 200)
+
+## 🤖 Baseline Agent
+
+To evaluate the baseline agent performance:
+```bash
+python src/baseline.py
+```

demo.py

@@ -0,0 +1,15 @@
+import gradio as gr
+
+def demo_function(name):
+    return f"Hello, {name if name else 'Developer'}! The OpenEnv Hackathon Demo is running successfully with the new updates!"
+
+if __name__ == "__main__":
+    print("Launching Gradio demo...")
+    demo = gr.Interface(
+        fn=demo_function, 
+        inputs=gr.Textbox(label="Enter your name", placeholder="Name..."), 
+        outputs=gr.Textbox(label="Message"),
+        title="OpenEnv Hackathon Submission Demo (Updated v2 ✨)",
+        description="A demo for your Hugging Face Space. This version has been updated to confirm your recent changes are now live!"
+    )
+    demo.launch()

openenv.yaml

@@ -0,0 +1,10 @@
+name: GPUClusterEnv
+version: 1.0.0
+description: A real-world cloud infrastructure environment where agents manage GPU provisioning to handle ML training workloads under strict budget constraints.
+endpoints:
+  reset: /reset
+  step: /step
+  state: /state
+  baseline: /baseline
+  grader: /grader
+  tasks: /tasks

requirements.txt

@@ -0,0 +1,9 @@
+gradio
+torch
+numpy
+gymnasium
+fastapi
+uvicorn
+pydantic
+numpy
+requests

src/__init__.py

@@ -0,0 +1 @@
+# Environment implementation goes here

src/baseline.py

@@ -0,0 +1,24 @@
+import requests
+
+BASE_URL = "http://localhost:7860" # Default HF space port
+
+def evaluate_baseline(task_id):
+    requests.post(f"{BASE_URL}/reset?task_id={task_id}")
+    done = False
+    
+    while not done:
+        state = requests.get(f"{BASE_URL}/state").json()["observation"]
+        
+        # Simple policy: If queue is larger than active GPUs, provision more.
+        gpus_needed = state["queue_size"] - state["active_gpus"]
+        action = {"gpus_to_provision": max(-1, min(2, gpus_needed))} # Throttle scaling
+        
+        step_res = requests.post(f"{BASE_URL}/step", json=action).json()
+        done = step_res["done"]
+        
+    score = requests.get(f"{BASE_URL}/grader").json()["score"]
+    print(f"Task: {task_id} | Final Score: {score:.3f}")
+
+if __name__ == "__main__":
+    for task in ["easy", "medium", "hard"]:
+        evaluate_baseline(task)

src/env.py

@@ -0,0 +1,57 @@
+import numpy as np
+from src.models import Observation, Action, StepResult, TaskConfig
+
+class GPUClusterEnv:
+    def __init__(self):
+        self.config = None
+        self.state = None
+        self.total_reward = 0.0
+
+    def reset(self, config: TaskConfig) -> Observation:
+        self.config = config
+        self.total_reward = 0.0
+        self.state = Observation(
+            time_step=0,
+            active_gpus=1,
+            queue_size=0,
+            current_budget=config.initial_budget,
+            incoming_jobs=0
+        )
+        return self.state
+
+    def step(self, action: Action) -> StepResult:
+        if self.state is None:
+            raise ValueError("Environment must be reset before calling step.")
+
+        # 1. Apply Action (Scale infrastructure)
+        self.state.active_gpus = max(0, self.state.active_gpus + action.gpus_to_provision)
+        
+        # 2. Simulate incoming workloads
+        new_jobs = np.random.poisson(self.config.job_arrival_rate)
+        self.state.incoming_jobs = new_jobs
+        self.state.queue_size += new_jobs
+
+        # 3. Process jobs (1 GPU processes 1 job per step)
+        jobs_processed = min(self.state.active_gpus, self.state.queue_size)
+        self.state.queue_size -= jobs_processed
+
+        # 4. Calculate Costs & Rewards
+        gpu_cost = self.state.active_gpus * 2.5  # $2.50 per step per GPU
+        sla_penalty = self.state.queue_size * 1.0 # $1 penalty per waiting job
+        
+        self.state.current_budget -= gpu_cost
+        
+        # Reward shaping
+        reward = (jobs_processed * 5.0) - gpu_cost - sla_penalty
+        self.total_reward += reward
+        self.state.time_step += 1
+
+        # 5. Terminal Conditions
+        done = self.state.time_step >= self.config.max_steps or self.state.current_budget <= 0
+
+        return StepResult(
+            observation=self.state,
+            reward=reward,
+            done=done,
+            info={"jobs_processed": jobs_processed, "total_reward": self.total_reward}
+        )

src/main.py

@@ -0,0 +1,55 @@
+from fastapi import FastAPI, HTTPException
+from src.models import Action, TaskConfig
+from src.env import GPUClusterEnv
+from src.tasks import TASKS
+import subprocess
+
+app = FastAPI(title="GPU Cluster OpenEnv")
+env = GPUClusterEnv()
+
+@app.get("/")
+def health_check():
+    return {"status": "ok", "message": "GPUClusterEnv is running"}
+
+@app.post("/reset")
+def reset_env(task_id: str = "easy"):
+    if task_id not in TASKS:
+        raise HTTPException(status_code=404, detail="Task not found")
+    obs = env.reset(TASKS[task_id])
+    return {"observation": obs.dict()}
+
+@app.post("/step")
+def step_env(action: Action):
+    try:
+        result = env.step(action)
+        return result.dict()
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+@app.get("/state")
+def get_state():
+    if env.state is None:
+        raise HTTPException(status_code=400, detail="Environment not initialized")
+    return {"observation": env.state.dict()}
+
+@app.get("/tasks")
+def list_tasks():
+    return {
+        "tasks": list(TASKS.keys()),
+        "action_schema": Action.schema()
+    }
+
+@app.get("/grader")
+def grader():
+    # Normalizes total reward to a 0.0 - 1.0 score based on max possible baseline
+    if env.state is None:
+        return {"score": 0.0}
+    max_expected_reward = env.config.max_steps * 10 # Arbitrary max for example
+    score = max(0.0, min(1.0, env.total_reward / max_expected_reward))
+    return {"score": score}
+
+@app.post("/baseline")
+def run_baseline():
+    # Trigger the baseline script and return results
+    result = subprocess.run(["python", "src/baseline.py"], capture_output=True, text=True)
+    return {"output": result.stdout}

src/models.py

@@ -0,0 +1,25 @@
+from pydantic import BaseModel
+from typing import List, Dict
+
+class Observation(BaseModel):
+    time_step: int
+    active_gpus: int
+    queue_size: int
+    current_budget: float
+    incoming_jobs: int
+
+class Action(BaseModel):
+    gpus_to_provision: int  # Can be positive (spin up) or negative (spin down)
+
+class StepResult(BaseModel):
+    observation: Observation
+    reward: float
+    done: bool
+    info: Dict
+
+class TaskConfig(BaseModel):
+    task_id: str
+    difficulty: str
+    max_steps: int
+    initial_budget: float
+    job_arrival_rate: float # Lambda for Poisson distribution

src/tasks.py

@@ -0,0 +1,7 @@
+from src.models import TaskConfig
+
+TASKS = {
+    "easy": TaskConfig(task_id="easy", difficulty="easy", max_steps=50, initial_budget=1000.0, job_arrival_rate=2.0),
+    "medium": TaskConfig(task_id="medium", difficulty="medium", max_steps=100, initial_budget=800.0, job_arrival_rate=5.0),
+    "hard": TaskConfig(task_id="hard", difficulty="hard", max_steps=200, initial_budget=500.0, job_arrival_rate=12.0),
+}