Upload folder using huggingface_hub

Dockerfile

@@ -0,0 +1,61 @@
+FROM python:3.11-slim
+
+LABEL maintainer="OpenEnv Hackathon"
+LABEL description="Autonomous Traffic Control – OpenEnv Environment (self-contained)"
+
+WORKDIR /app
+
+# ── Install system deps ────────────────────────────────────────────────────
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# ── Copy packaging manifest first (layer-cache friendly) ──────────────────
+COPY pyproject.toml README.md ./
+
+# ── Install Python deps ────────────────────────────────────────────────────
+RUN pip install --no-cache-dir \
+    "openenv-core[core]>=0.2.2" \
+    "openai>=1.0.0" \
+    "gradio>=4.0.0" \
+    "numpy>=1.24.0" \
+    "python-dotenv>=1.0.0" \
+    "fastapi>=0.104.0" \
+    "uvicorn[standard]>=0.24.0" \
+    "pydantic>=2.5.0" \
+    "requests>=2.31.0" \
+    "python-multipart>=0.0.6"
+
+# ── Copy source (self-contained; no root-level deps needed) ───────────────
+COPY models.py ./traffic_control/models.py
+COPY environment.py ./traffic_control/environment.py
+COPY tasks.py ./traffic_control/tasks.py
+COPY client.py ./traffic_control/client.py
+COPY __init__.py ./traffic_control/__init__.py
+COPY inference.py ./traffic_control/inference.py
+COPY openenv.yaml ./traffic_control/openenv.yaml
+COPY server/ ./traffic_control/server/
+
+# ── Create package anchor so Python treats traffic_control/ as the package ─
+RUN echo "" > ./traffic_control/__init__.py || true
+
+# ── Install the package in editable mode ──────────────────────────────────
+RUN pip install --no-cache-dir -e .
+
+# ── Runtime config ────────────────────────────────────────────────────────
+ENV WORKERS=2
+ENV PORT=8000
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+EXPOSE 8000
+
+HEALTHCHECK --interval=15s --timeout=5s --start-period=15s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"
+
+ENV ENABLE_WEB_INTERFACE=true
+CMD ["sh", "-c", \
+     "uvicorn traffic_control.server.app:app \
+      --host 0.0.0.0 \
+      --port ${PORT} \
+      --workers ${WORKERS}"]

README.md

@@ -1,10 +1,255 @@
 ---
-title: Sst Hack
-emoji: 💻
+title: Traffic Control Environment Server
+emoji: 🎯
 colorFrom: gray
-colorTo: red
+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
+# Traffic Control 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 Traffic Control environment is through the `TrafficControlEnv` class:
+
+```python
+from traffic_control import TrafficControlAction, TrafficControlEnv
+
+try:
+    # Create environment from Docker image
+    traffic_controlenv = TrafficControlEnv.from_docker_image("traffic_control-env:latest")
+
+    # Reset
+    result = traffic_controlenv.reset()
+    print(f"Reset: {result.observation.echoed_message}")
+
+    # Send multiple messages
+    messages = ["Hello, World!", "Testing echo", "Final message"]
+
+    for msg in messages:
+        result = traffic_controlenv.step(TrafficControlAction(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
+    traffic_controlenv.close()
+```
+
+That's it! The `TrafficControlEnv.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 traffic_control-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
+**TrafficControlAction**: Contains a single field
+- `message` (str) - The message to echo back
+
+### Observation
+**TrafficControlObservation**: 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 Traffic Control environment server running, you can connect directly:
+
+```python
+from traffic_control import TrafficControlEnv
+
+# Connect to existing server
+traffic_controlenv = TrafficControlEnv(base_url="<ENV_HTTP_URL_HERE>")
+
+# Use as normal
+result = traffic_controlenv.reset()
+result = traffic_controlenv.step(TrafficControlAction(message="Hello!"))
+```
+
+Note: When connecting to an existing server, `traffic_controlenv.close()` will NOT stop the server.
+
+### Using the Context Manager
+
+The client supports context manager usage for automatic connection management:
+
+```python
+from traffic_control import TrafficControlAction, TrafficControlEnv
+
+# Connect with context manager (auto-connects and closes)
+with TrafficControlEnv(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(TrafficControlAction(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(
+    TrafficControlEnvironment,  # Pass class, not instance
+    TrafficControlAction,
+    TrafficControlObservation,
+    max_concurrent_envs=4,  # Allow 4 concurrent sessions
+)
+```
+
+Then multiple clients can connect simultaneously:
+
+```python
+from traffic_control import TrafficControlAction, TrafficControlEnv
+from concurrent.futures import ThreadPoolExecutor
+
+def run_episode(client_id: int):
+    with TrafficControlEnv(base_url="http://localhost:8000") as env:
+        result = env.reset()
+        for i in range(10):
+            result = env.step(TrafficControlAction(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/traffic_control_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
+
+```
+traffic_control/
+├── .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              # TrafficControlEnv client
+├── models.py              # Action and Observation models
+└── server/
+    ├── __init__.py        # Server module exports
+    ├── traffic_control_environment.py  # Core environment logic
+    ├── app.py             # FastAPI application (HTTP + WebSocket endpoints)
+    └── Dockerfile         # Container image definition
+```

__init__.py

@@ -0,0 +1,13 @@
+"""Traffic Control Environment package."""
+
+from .models import TrafficAction, TrafficObservation, TrafficState
+from .client import TrafficControlEnv
+from .environment import TrafficControlEnvironment
+
+__all__ = [
+    "TrafficAction",
+    "TrafficObservation",
+    "TrafficState",
+    "TrafficControlEnv",
+    "TrafficControlEnvironment",
+]

client.py

@@ -0,0 +1,45 @@
+"""HTTP/WebSocket client for the Autonomous Traffic Control environment."""
+
+from typing import Any, Dict
+from openenv.core.env_client import EnvClient, StepResult
+
+from .models import TrafficAction, TrafficObservation, TrafficState
+
+
+class TrafficControlEnv(EnvClient[TrafficAction, TrafficObservation, TrafficState]):
+    """
+    Client for the Autonomous Traffic Control environment.
+
+    Inherits all openenv-core EnvClient functionality:
+    - async context manager
+    - .sync() wrapper for synchronous use
+    - reset() / step() / state()
+    - from_docker_image() for local Docker deployment
+    - from_env() for HuggingFace Space deployment
+
+    Example (sync):
+        with TrafficControlEnv(base_url="http://localhost:8000").sync() as env:
+            obs = env.reset(task_id="basic_flow", seed=42)
+            while not obs.done:
+                obs = env.step(TrafficAction(light_phase=0))
+
+    Example (async):
+        async with TrafficControlEnv(base_url="http://localhost:8000") as env:
+            obs = await env.reset(task_id="emergency_priority", seed=0)
+            while not obs.done:
+                obs = await env.step(TrafficAction(light_phase=1))
+    """
+
+    def _step_payload(self, action: TrafficAction) -> Dict[str, Any]:
+        return action.model_dump()
+
+    def _parse_result(self, payload: Dict[str, Any]) -> StepResult[TrafficObservation]:
+        obs = TrafficObservation(**payload["observation"])
+        return StepResult(
+            observation=obs,
+            reward=payload.get("reward"),
+            done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: Dict[str, Any]) -> TrafficState:
+        return TrafficState(**payload)

environment.py

@@ -0,0 +1,438 @@
+"""
+Core simulation for the Autonomous Traffic Control Environment.
+
+Implements openenv-core's Environment interface so it works directly
+with create_app() — no adapters needed.
+
+Simulates a 4-way intersection with:
+  - Poisson vehicle arrivals per approach
+  - Emergency vehicles with urgency levels (0-10)
+  - Yellow-light transition state machine (2-step yellow)
+  - Traffic-surge events (hard task only)
+  - Multi-objective reward function
+"""
+
+from __future__ import annotations
+
+import math
+import random
+import uuid
+from dataclasses import dataclass
+from enum import IntEnum
+from typing import Dict, List, Optional, Set, Tuple
+
+from openenv.core.env_server.interfaces import Environment
+
+from .models import (
+    TrafficAction,
+    TrafficObservation,
+    TrafficState,
+    PHASE_NS_GREEN,
+    PHASE_EW_GREEN,
+    PHASE_ALL_RED,
+    PHASE_NS_YELLOW,
+    PHASE_EW_YELLOW,
+)
+
+
+# ---------------------------------------------------------------------------
+# Internal enums
+# ---------------------------------------------------------------------------
+
+class VehicleType(IntEnum):
+    CAR       = 0
+    BUS       = 1
+    EMERGENCY = 2
+
+
+class Direction(IntEnum):
+    NORTH = 0
+    SOUTH = 1
+    EAST  = 2
+    WEST  = 3
+
+
+class LightPhase(IntEnum):
+    NS_GREEN  = PHASE_NS_GREEN
+    EW_GREEN  = PHASE_EW_GREEN
+    ALL_RED   = PHASE_ALL_RED
+    NS_YELLOW = PHASE_NS_YELLOW
+    EW_YELLOW = PHASE_EW_YELLOW
+
+
+# ---------------------------------------------------------------------------
+# Phase transition tables
+# ---------------------------------------------------------------------------
+
+PHASE_ALLOWS: Dict[LightPhase, Set[int]] = {
+    LightPhase.NS_GREEN:  {Direction.NORTH, Direction.SOUTH},
+    LightPhase.EW_GREEN:  {Direction.EAST,  Direction.WEST},
+    LightPhase.ALL_RED:   set(),
+    LightPhase.NS_YELLOW: {Direction.NORTH, Direction.SOUTH},
+    LightPhase.EW_YELLOW: {Direction.EAST,  Direction.WEST},
+}
+
+PHASE_FLOW_RATE: Dict[LightPhase, int] = {
+    LightPhase.NS_GREEN:  3,
+    LightPhase.EW_GREEN:  3,
+    LightPhase.ALL_RED:   0,
+    LightPhase.NS_YELLOW: 1,
+    LightPhase.EW_YELLOW: 1,
+}
+
+YELLOW_DURATION = 2
+
+
+# ---------------------------------------------------------------------------
+# Task configurations
+# ---------------------------------------------------------------------------
+
+TASK_CONFIGS: Dict[str, dict] = {
+    "basic_flow": {
+        "vehicle_arrival_rate":    0.4,
+        "emergency_arrival_rate":  0.0,
+        "emergency_urgency_range": (0, 0),
+        "max_steps":               200,
+        "max_queue_per_lane":      20,
+        "surge_probability":       0.0,
+        "surge_multiplier":        1.0,
+    },
+    "emergency_priority": {
+        "vehicle_arrival_rate":    0.5,
+        "emergency_arrival_rate":  0.015,
+        "emergency_urgency_range": (7, 10),
+        "max_steps":               300,
+        "max_queue_per_lane":      20,
+        "surge_probability":       0.0,
+        "surge_multiplier":        1.0,
+    },
+    "dynamic_scenarios": {
+        "vehicle_arrival_rate":    0.7,
+        "emergency_arrival_rate":  0.035,
+        "emergency_urgency_range": (8, 10),
+        "max_steps":               400,
+        "max_queue_per_lane":      30,
+        "surge_probability":       0.04,
+        "surge_multiplier":        3.0,
+    },
+}
+
+
+# ---------------------------------------------------------------------------
+# Internal vehicle dataclass
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Vehicle:
+    vehicle_type: VehicleType
+    direction: Direction
+    waiting_time: int = 0
+    urgency: int = 0
+
+
+# ---------------------------------------------------------------------------
+# Environment
+# ---------------------------------------------------------------------------
+
+class TrafficControlEnvironment(Environment):
+    """
+    OpenEnv-compliant Autonomous Traffic Control environment.
+
+    Inherits from openenv.core.env_server.interfaces.Environment,
+    making it compatible with openenv-core's create_app() factory.
+
+    Methods
+    -------
+    reset(seed, episode_id, **kwargs) -> TrafficObservation
+    step(action)                      -> TrafficObservation
+    state (property)                  -> TrafficState
+    """
+
+    SUPPORTS_CONCURRENT_SESSIONS: bool = True
+
+    def __init__(self, task_id: str = "basic_flow") -> None:
+        if task_id not in TASK_CONFIGS:
+            raise ValueError(
+                f"Unknown task_id '{task_id}'. "
+                f"Valid options: {list(TASK_CONFIGS.keys())}"
+            )
+        self.task_id = task_id
+        self._cfg = TASK_CONFIGS[task_id]
+        self._rng = random.Random()
+
+        self._episode_id: str = ""
+        self._step_count: int = 0
+        self._queues: List[List[Vehicle]] = [[] for _ in range(4)]
+        self._current_phase: LightPhase = LightPhase.NS_GREEN
+        self._time_in_phase: int = 0
+        self._pending_phase: Optional[int] = None
+
+        self._total_vehicles_passed: int   = 0
+        self._total_emergency_passed: int  = 0
+        self._total_waiting_time: float    = 0.0
+        self._total_emergency_delay: float = 0.0
+        self._total_collisions: int        = 0
+        self._total_phase_changes: int     = 0
+
+    # ------------------------------------------------------------------
+    # openenv-core Environment interface
+    # ------------------------------------------------------------------
+
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        task_id: Optional[str] = None,
+        **kwargs,
+    ) -> TrafficObservation:
+        """Start a fresh episode."""
+        if task_id and task_id in TASK_CONFIGS:
+            self.task_id = task_id
+            self._cfg = TASK_CONFIGS[task_id]
+
+        self._rng         = random.Random(seed)
+        self._episode_id  = episode_id or str(uuid.uuid4())
+        self._step_count  = 0
+        self._queues      = [[] for _ in range(4)]
+        self._current_phase = LightPhase.NS_GREEN
+        self._time_in_phase = 0
+        self._pending_phase = None
+
+        self._total_vehicles_passed   = 0
+        self._total_emergency_passed  = 0
+        self._total_waiting_time      = 0.0
+        self._total_emergency_delay   = 0.0
+        self._total_collisions        = 0
+        self._total_phase_changes     = 0
+
+        return self._build_obs(0, 0, 0.0, False, 0.0, False)
+
+    def step(self, action: TrafficAction) -> TrafficObservation:  # type: ignore[override]
+        """Execute one simulation step."""
+        self._step_count += 1
+
+        self._spawn_vehicles()
+        phase_changed = self._apply_action(action)
+        self._advance_phase()
+        vehicles_passed, emergency_passed = self._flow_traffic()
+        waiting_delta = self._tick_waiting_times()
+        collision = self._check_collision()
+        reward = self._compute_reward(
+            vehicles_passed, emergency_passed, waiting_delta, collision, phase_changed
+        )
+
+        self._total_vehicles_passed  += vehicles_passed
+        self._total_emergency_passed += emergency_passed
+        self._total_waiting_time     += waiting_delta
+        if collision:
+            self._total_collisions += 1
+
+        done = collision or self._step_count >= self._cfg["max_steps"]
+        return self._build_obs(vehicles_passed, emergency_passed, waiting_delta, collision, reward, done)
+
+    @property
+    def state(self) -> TrafficState:
+        """Return cumulative episode-level state."""
+        return TrafficState(
+            episode_id=self._episode_id,
+            step_count=self._step_count,
+            task_id=self.task_id,
+            total_vehicles_passed=self._total_vehicles_passed,
+            total_emergency_passed=self._total_emergency_passed,
+            total_waiting_time=self._total_waiting_time,
+            total_emergency_delay=self._total_emergency_delay,
+            total_collisions=self._total_collisions,
+            total_phase_changes=self._total_phase_changes,
+        )
+
+    # ------------------------------------------------------------------
+    # Simulation internals
+    # ------------------------------------------------------------------
+
+    def _spawn_vehicles(self) -> None:
+        arr     = self._cfg["vehicle_arrival_rate"]
+        em      = self._cfg["emergency_arrival_rate"]
+        urg     = self._cfg["emergency_urgency_range"]
+        surge_p = self._cfg["surge_probability"]
+        surge_m = self._cfg["surge_multiplier"]
+        max_q   = self._cfg["max_queue_per_lane"]
+
+        surge_dir   = -1
+        surge_extra = 0
+        if surge_p > 0.0 and self._rng.random() < surge_p:
+            surge_dir   = self._rng.randint(0, 3)
+            surge_extra = max(0, int(self._rng.gauss(3, 1) * surge_m))
+
+        for d in range(4):
+            n = self._poisson(arr)
+            if d == surge_dir:
+                n += surge_extra
+            for _ in range(n):
+                if len(self._queues[d]) < max_q:
+                    vt = VehicleType.BUS if self._rng.random() < 0.10 else VehicleType.CAR
+                    self._queues[d].append(Vehicle(vt, Direction(d)))
+
+            if em > 0.0 and self._rng.random() < em:
+                if len(self._queues[d]) < max_q:
+                    urgency = self._rng.randint(urg[0], urg[1])
+                    self._queues[d].insert(
+                        0,
+                        Vehicle(VehicleType.EMERGENCY, Direction(d), urgency=urgency),
+                    )
+
+    def _apply_action(self, action: TrafficAction) -> bool:
+        req = action.light_phase
+        if req not in (PHASE_NS_GREEN, PHASE_EW_GREEN, PHASE_ALL_RED):
+            return False
+        if self._current_phase in (LightPhase.NS_YELLOW, LightPhase.EW_YELLOW):
+            return False
+        current_base = int(self._current_phase)
+        if current_base == req:
+            return False
+
+        self._total_phase_changes += 1
+        self._pending_phase = req
+
+        if req == PHASE_ALL_RED:
+            self._current_phase = LightPhase.ALL_RED
+            self._time_in_phase = 0
+            self._pending_phase = None
+        elif self._current_phase == LightPhase.NS_GREEN:
+            self._current_phase = LightPhase.NS_YELLOW
+            self._time_in_phase = 0
+        elif self._current_phase == LightPhase.EW_GREEN:
+            self._current_phase = LightPhase.EW_YELLOW
+            self._time_in_phase = 0
+        elif self._current_phase == LightPhase.ALL_RED:
+            self._current_phase = LightPhase(req)
+            self._time_in_phase = 0
+            self._pending_phase = None
+
+        return True
+
+    def _advance_phase(self) -> None:
+        self._time_in_phase += 1
+        if self._current_phase in (LightPhase.NS_YELLOW, LightPhase.EW_YELLOW):
+            if self._time_in_phase >= YELLOW_DURATION:
+                target = self._pending_phase if self._pending_phase is not None else PHASE_ALL_RED
+                self._current_phase = LightPhase(target)
+                self._time_in_phase = 0
+                self._pending_phase = None
+
+    def _flow_traffic(self) -> Tuple[int, int]:
+        allowed   = PHASE_ALLOWS[self._current_phase]
+        flow_rate = PHASE_FLOW_RATE[self._current_phase]
+        vehicles_passed  = 0
+        emergency_passed = 0
+
+        for d in allowed:
+            queue      = self._queues[int(d)]
+            passed_dir = 0
+            while queue and passed_dir < flow_rate:
+                vehicle = queue.pop(0)
+                passed_dir += 1
+                if vehicle.vehicle_type == VehicleType.EMERGENCY:
+                    emergency_passed += 1
+                else:
+                    vehicles_passed += 1
+
+        return vehicles_passed, emergency_passed
+
+    def _tick_waiting_times(self) -> float:
+        total = 0.0
+        for d in range(4):
+            for v in self._queues[d]:
+                v.waiting_time += 1
+                total += 1.0
+                if v.vehicle_type == VehicleType.EMERGENCY:
+                    self._total_emergency_delay += 1.0
+        return total
+
+    def _check_collision(self) -> bool:
+        total_queued = sum(len(q) for q in self._queues)
+        if total_queued > 40 and self._time_in_phase > 20:
+            return self._rng.random() < 0.04
+        return False
+
+    def _compute_reward(
+        self,
+        vehicles_passed: int,
+        emergency_passed: int,
+        waiting_delta: float,
+        collision: bool,
+        phase_changed: bool,
+    ) -> float:
+        r  = vehicles_passed  * 0.20
+        r += emergency_passed * 10.0
+        r -= waiting_delta    * 0.05
+
+        for d in range(4):
+            for v in self._queues[d]:
+                if v.vehicle_type == VehicleType.EMERGENCY:
+                    r -= v.urgency * 0.4
+
+        if collision:
+            r -= 200.0
+
+        if phase_changed:
+            p = int(self._current_phase)
+            if p == PHASE_NS_GREEN:
+                if (len(self._queues[0]) + len(self._queues[1])) == 0:
+                    r -= 0.5
+            elif p == PHASE_EW_GREEN:
+                if (len(self._queues[2]) + len(self._queues[3])) == 0:
+                    r -= 0.5
+
+        return r
+
+    def _build_obs(
+        self,
+        vehicles_passed: int,
+        emergency_passed: int,
+        waiting_delta: float,
+        collision: bool,
+        reward: float,
+        done: bool,
+    ) -> TrafficObservation:
+        queue_lengths     = []
+        emergency_queue   = []
+        emergency_urgency = []
+
+        for d in range(4):
+            reg   = sum(1 for v in self._queues[d] if v.vehicle_type != VehicleType.EMERGENCY)
+            em    = sum(1 for v in self._queues[d] if v.vehicle_type == VehicleType.EMERGENCY)
+            max_u = max(
+                (v.urgency for v in self._queues[d] if v.vehicle_type == VehicleType.EMERGENCY),
+                default=0,
+            )
+            queue_lengths.append(reg)
+            emergency_queue.append(em)
+            emergency_urgency.append(max_u)
+
+        return TrafficObservation(
+            current_phase=int(self._current_phase),
+            time_in_phase=self._time_in_phase,
+            queue_lengths=queue_lengths,
+            emergency_queue=emergency_queue,
+            emergency_urgency=emergency_urgency,
+            vehicles_passed=vehicles_passed,
+            emergency_passed=emergency_passed,
+            total_waiting_time=waiting_delta,
+            collision=collision,
+            reward=reward,
+            done=done,
+            metadata={
+                "step_count": self._step_count,
+                "task_id":    self.task_id,
+            },
+        )
+
+    def _poisson(self, lam: float) -> int:
+        if lam <= 0.0:
+            return 0
+        threshold = math.exp(-lam)
+        k, p = 0, 1.0
+        while p > threshold:
+            k += 1
+            p *= self._rng.random()
+        return k - 1

inference.py

@@ -0,0 +1,259 @@
+"""
+Inference Script — Autonomous Traffic Control OpenEnv Environment
+=================================================================
+Mandatory env variables:
+    API_BASE_URL   LLM endpoint  (default: https://api.openai.com/v1)
+    MODEL_NAME     Model to use  (default: gpt-4.1-mini)
+    HF_TOKEN       Your Hugging Face / LLM API key  ← REQUIRED
+
+Optional:
+    SERVER_URL     Running env server (default: http://localhost:8000)
+
+Run:
+    HF_TOKEN=<key> python inference.py
+    HF_TOKEN=<key> SERVER_URL=http://localhost:8000 python inference.py
+"""
+
+import os
+import sys
+import json
+import textwrap
+import requests as _http
+
+# Allow running directly from traffic_control/ OR from its parent
+_HERE = os.path.dirname(os.path.abspath(__file__))
+_PARENT = os.path.dirname(_HERE)
+for _p in (_HERE, _PARENT):
+    if _p not in sys.path:
+        sys.path.insert(0, _p)
+
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:
+    pass
+
+from openai import OpenAI
+
+# Import from within the self-contained package
+try:
+    from traffic_control.client import TrafficControlEnv
+    from traffic_control.models import TrafficAction, TrafficObservation
+except ImportError:
+    from client import TrafficControlEnv
+    from models import TrafficAction, TrafficObservation
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+API_BASE_URL: str = os.getenv("API_BASE_URL", "https://api.openai.com/v1")
+MODEL_NAME:   str = os.getenv("MODEL_NAME", "gpt-4.1-mini")
+HF_TOKEN:     str = os.getenv("HF_TOKEN", "")
+SERVER_URL:   str = os.getenv("SERVER_URL", "http://localhost:8000")
+
+if not HF_TOKEN:
+    raise ValueError("HF_TOKEN environment variable is required")
+
+SEED        = 42
+MAX_TOKENS  = 32
+TEMPERATURE = 0.0
+
+llm_client = OpenAI(base_url=API_BASE_URL, api_key=HF_TOKEN)
+
+# ---------------------------------------------------------------------------
+# Prompts
+# ---------------------------------------------------------------------------
+
+SYSTEM_PROMPT = textwrap.dedent("""
+    You are an Autonomous Traffic Control AI managing a 4-way intersection.
+
+    OBJECTIVE: Maximise vehicle throughput and prioritise emergency vehicles.
+
+    PHASES:
+      0 = North-South Green  (N/S vehicles may pass)
+      1 = East-West Green    (E/W vehicles may pass)
+      2 = All Red            (no vehicles pass — use only for emergency clearance)
+
+    STRATEGY:
+      1. If any emergency vehicles are waiting, switch to their direction immediately.
+      2. Otherwise, switch to the direction with the most queued vehicles.
+      3. Avoid changing phase too frequently (wait ≥ 4 steps per phase).
+
+    OUTPUT: Reply with exactly one JSON object — no markdown, no explanation:
+      {"light_phase": <0, 1, or 2>}
+""").strip()
+
+
+def _build_prompt(obs: TrafficObservation) -> str:
+    q    = obs.queue_lengths
+    em_q = obs.emergency_queue
+    em_u = obs.emergency_urgency
+    return textwrap.dedent(f"""
+        CURRENT STATE:
+          Active phase      : {obs.current_phase}
+          Steps in phase    : {obs.time_in_phase}
+          Regular queue     : N={q[0]}, S={q[1]}, E={q[2]}, W={q[3]}
+          Emergency queue   : N={em_q[0]}, S={em_q[1]}, E={em_q[2]}, W={em_q[3]}
+          Emergency urgency : N={em_u[0]}, S={em_u[1]}, E={em_u[2]}, W={em_u[3]}
+
+        Output exactly: {{"light_phase": 0}}
+    """).strip()
+
+# ---------------------------------------------------------------------------
+# Rule-based fallback (used when LLM call fails)
+# ---------------------------------------------------------------------------
+
+def _rule_based_action(obs: TrafficObservation) -> TrafficAction:
+    """Simple heuristic: emergency first, else highest queue."""
+    em_q = obs.emergency_queue
+    q    = obs.queue_lengths
+
+    # Emergency vehicle present?
+    if sum(em_q) > 0:
+        if em_q[0] + em_q[1] >= em_q[2] + em_q[3]:
+            return TrafficAction(light_phase=0)  # NS Green
+        else:
+            return TrafficAction(light_phase=1)  # EW Green
+
+    # Highest queue direction
+    ns_total = q[0] + q[1]
+    ew_total = q[2] + q[3]
+    if obs.current_phase == 0 and obs.time_in_phase < 4:
+        return TrafficAction(light_phase=0)
+    if obs.current_phase == 1 and obs.time_in_phase < 4:
+        return TrafficAction(light_phase=1)
+    return TrafficAction(light_phase=0 if ns_total >= ew_total else 1)
+
+# ---------------------------------------------------------------------------
+# LLM action
+# ---------------------------------------------------------------------------
+
+def get_llm_action(obs: TrafficObservation) -> TrafficAction:
+    try:
+        resp = llm_client.chat.completions.create(
+            model=MODEL_NAME,
+            messages=[
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user",   "content": _build_prompt(obs)},
+            ],
+            response_format={"type": "json_object"},
+            temperature=TEMPERATURE,
+            max_tokens=MAX_TOKENS,
+        )
+        data  = json.loads(resp.choices[0].message.content or "{}")
+        phase = int(data.get("light_phase", obs.current_phase))
+        phase = max(0, min(2, phase))
+        return TrafficAction(light_phase=phase)
+    except Exception:
+        return _rule_based_action(obs)
+
+# ---------------------------------------------------------------------------
+# Grade fetcher  (calls /grade after episode ends)
+# ---------------------------------------------------------------------------
+
+def _fetch_score(task_id: str, state_payload: dict) -> float:
+    """Call the /grade endpoint and return a clamped (0.001, 0.999) score."""
+    try:
+        r = _http.post(
+            f"{SERVER_URL}/grade",
+            json={
+                "task_id":               task_id,
+                "total_vehicles_passed": state_payload.get("total_vehicles_passed", 0),
+                "total_emergency_passed":state_payload.get("total_emergency_passed", 0),
+                "total_waiting_time":    state_payload.get("total_waiting_time", 0.0),
+                "total_collisions":      state_payload.get("total_collisions", 0),
+                "total_emergency_delay": state_payload.get("total_emergency_delay", 0.0),
+                "total_phase_changes":   state_payload.get("total_phase_changes", 0),
+                "step_count":            max(state_payload.get("step_count", 1), 1),
+            },
+            timeout=10,
+        )
+        if r.status_code == 200:
+            raw = float(r.json().get("score", 0.5))
+            return max(0.001, min(0.999, raw))
+    except Exception:
+        pass
+    return 0.5  # safe fallback
+
+
+# ---------------------------------------------------------------------------
+# Task runner
+# ---------------------------------------------------------------------------
+
+def run_task(task_id: str) -> None:
+    print(f"[START] task={task_id} env=traffic-control model={MODEL_NAME}")
+
+    rewards: list[float] = []
+    success = False
+
+    try:
+        with TrafficControlEnv(base_url=SERVER_URL).sync() as env:
+            step_result = env.reset(task_id=task_id, seed=SEED)
+            step = 1
+
+            while not step_result.done:
+                obs       = step_result.observation
+                error_msg = "null"
+
+                try:
+                    action = get_llm_action(obs)
+                except Exception as exc:
+                    error_msg = str(exc).replace('"', "'").replace("\\", "")
+                    action    = _rule_based_action(obs)
+
+                action_str = f"TrafficAction(light_phase={action.light_phase})"
+
+                try:
+                    step_result = env.step(action)
+                    done_str    = "true" if step_result.done else "false"
+                    reward_val  = step_result.reward if step_result.reward is not None else 0.0
+                    rewards.append(reward_val)
+                    print(
+                        f"[STEP] step={step} action={action_str} "
+                        f"reward={reward_val:.2f} done={done_str} error={error_msg}"
+                    )
+                except Exception as exc:
+                    env_error = str(exc).replace('"', "'").replace("\\", "")
+                    print(
+                        f"[STEP] step={step} action={action_str} "
+                        f"reward=0.00 done=true error={env_error}"
+                    )
+                    break
+
+                step += 1
+
+            success = True
+
+    except Exception as exc:
+        print(f"[STEP] step=0 action=none reward=0.00 done=true error={exc}")
+        success = False
+
+    success_str = "true" if success else "false"
+    rewards_str = ",".join(f"{r:.2f}" for r in rewards) if rewards else "0.00"
+
+    # Fetch final grade score from /grade endpoint
+    score = 0.5
+    try:
+        state_resp = _http.get(f"{SERVER_URL}/state", timeout=10)
+        if state_resp.status_code == 200:
+            score = _fetch_score(task_id, state_resp.json())
+    except Exception:
+        pass
+
+    print(f"[END] success={success_str} steps={len(rewards)} score={score:.3f} rewards={rewards_str}")
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    tasks = ["basic_flow", "emergency_priority", "dynamic_scenarios"]
+    for task in tasks:
+        run_task(task)
+        print()  # blank line between tasks
+
+
+if __name__ == "__main__":
+    main()

models.py

@@ -0,0 +1,120 @@
+"""
+Typed data models for the Autonomous Traffic Control Environment.
+
+All Pydantic models extend openenv-core base types so the environment
+is fully compliant with the OpenEnv specification.
+"""
+
+from typing import List, Optional, Any, Dict
+from openenv.core.env_server.types import Action, Observation, State
+from pydantic import Field
+
+
+# ---------------------------------------------------------------------------
+# Phase / direction constants
+# ---------------------------------------------------------------------------
+
+PHASE_NS_GREEN  = 0   # North-South green, East-West red
+PHASE_EW_GREEN  = 1   # East-West green, North-South red
+PHASE_ALL_RED   = 2   # All approaches red (emergency clearance)
+PHASE_NS_YELLOW = 3   # North-South transitioning to red
+PHASE_EW_YELLOW = 4   # East-West transitioning to red
+
+DIRECTION_NORTH = 0
+DIRECTION_SOUTH = 1
+DIRECTION_EAST  = 2
+DIRECTION_WEST  = 3
+
+
+# ---------------------------------------------------------------------------
+# Action
+# ---------------------------------------------------------------------------
+
+class TrafficAction(Action):
+    """
+    Agent action: set the desired traffic light phase.
+
+    light_phase:
+        0 = NS_GREEN  – North + South get green, East + West get red.
+        1 = EW_GREEN  – East + West get green, North + South get red.
+        2 = ALL_RED   – All approaches red; use for emergency clearance.
+    """
+    light_phase: int = Field(
+        ...,
+        ge=0, le=2,
+        description="Desired light phase: 0=NS_GREEN | 1=EW_GREEN | 2=ALL_RED",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Observation
+# ---------------------------------------------------------------------------
+
+class TrafficObservation(Observation):
+    """
+    Full observation returned by reset() and step().
+
+    Directions index: 0=North, 1=South, 2=East, 3=West
+    The `done`, `reward`, and `metadata` fields are inherited from
+    openenv.core.env_server.types.Observation.
+    """
+
+    # -- Traffic-light state --
+    current_phase: int = Field(
+        default=0,
+        description="Active light phase: 0=NS_GREEN|1=EW_GREEN|2=ALL_RED|3=NS_YELLOW|4=EW_YELLOW",
+    )
+    time_in_phase: int = Field(
+        default=0,
+        description="Steps elapsed since last phase change",
+    )
+
+    # -- Vehicle queues (one per direction [N, S, E, W]) --
+    queue_lengths: List[int] = Field(
+        default_factory=lambda: [0, 0, 0, 0],
+        description="Regular vehicle count per approach [N, S, E, W]",
+    )
+    emergency_queue: List[int] = Field(
+        default_factory=lambda: [0, 0, 0, 0],
+        description="Emergency vehicle count per approach [N, S, E, W]",
+    )
+    emergency_urgency: List[int] = Field(
+        default_factory=lambda: [0, 0, 0, 0],
+        description="Max urgency (0-10) of waiting emergency vehicles per approach",
+    )
+
+    # -- Flow metrics for this step --
+    vehicles_passed: int = Field(default=0, description="Regular vehicles cleared this step")
+    emergency_passed: int = Field(default=0, description="Emergency vehicles cleared this step")
+
+    # -- Penalty signals --
+    total_waiting_time: float = Field(
+        default=0.0,
+        description="Sum of per-vehicle waiting increments this step",
+    )
+    collision: bool = Field(default=False, description="Gridlock-induced collision flag")
+
+
+# ---------------------------------------------------------------------------
+# State
+# ---------------------------------------------------------------------------
+
+class TrafficState(State):
+    """
+    Episode-level cumulative state, returned by state().
+
+    The `episode_id` and `step_count` fields are inherited from
+    openenv.core.env_server.types.State.
+    """
+    task_id: str = Field(default="basic_flow", description="Active task ID")
+
+    # Cumulative episode metrics
+    total_vehicles_passed: int = Field(default=0)
+    total_emergency_passed: int = Field(default=0)
+    total_waiting_time: float = Field(default=0.0)
+    total_emergency_delay: float = Field(
+        default=0.0,
+        description="Steps emergency vehicles spent waiting",
+    )
+    total_collisions: int = Field(default=0)
+    total_phase_changes: int = Field(default=0)

openenv.yaml

@@ -0,0 +1,147 @@
+id: traffic-control
+name: Autonomous Traffic Control Environment
+version: "1.0.0"
+description: >
+  A 4-way intersection RL environment where an AI agent controls traffic lights
+  to maximise vehicle throughput and prioritise emergency vehicles.
+  Compliant with the OpenEnv reset / step / state API specification.
+
+author: OpenEnv Hackathon Submission
+tags:
+  - reinforcement-learning
+  - traffic-control
+  - emergency-vehicles
+  - autonomous-systems
+  - openenv
+
+# ---------------------------------------------------------------------------
+# Observation space
+# ---------------------------------------------------------------------------
+observation_space:
+  type: object
+  properties:
+    current_phase:
+      type: integer
+      enum: [0, 1, 2, 3, 4]
+      description: >
+        Active traffic-light phase.
+        0=NS_GREEN | 1=EW_GREEN | 2=ALL_RED | 3=NS_YELLOW | 4=EW_YELLOW
+    time_in_phase:
+      type: integer
+      minimum: 0
+      description: Steps elapsed since the last phase change.
+    queue_lengths:
+      type: array
+      items: { type: integer, minimum: 0 }
+      minItems: 4
+      maxItems: 4
+      description: "Regular vehicle queue depth per approach [N, S, E, W]."
+    emergency_queue:
+      type: array
+      items: { type: integer, minimum: 0 }
+      minItems: 4
+      maxItems: 4
+      description: "Emergency vehicle count per approach [N, S, E, W]."
+    emergency_urgency:
+      type: array
+      items: { type: integer, minimum: 0, maximum: 10 }
+      minItems: 4
+      maxItems: 4
+      description: "Max urgency of waiting emergency vehicles per approach (0 = none)."
+    vehicles_passed:
+      type: integer
+      minimum: 0
+      description: Regular vehicles that cleared the intersection this step.
+    emergency_passed:
+      type: integer
+      minimum: 0
+      description: Emergency vehicles that cleared the intersection this step.
+    total_waiting_time:
+      type: number
+      description: Sum of per-vehicle waiting increments accumulated this step.
+    collision:
+      type: boolean
+      description: True if a gridlock-induced collision occurred this step.
+    reward:
+      type: number
+      description: Step reward computed by the environment.
+    done:
+      type: boolean
+      description: True when the episode has ended.
+    metadata:
+      type: object
+      description: Auxiliary info (step_count, task_id, …).
+
+# ---------------------------------------------------------------------------
+# Action space
+# ---------------------------------------------------------------------------
+action_space:
+  type: object
+  properties:
+    light_phase:
+      type: integer
+      enum: [0, 1, 2]
+      description: >
+        Desired traffic-light phase.
+        0=NS_GREEN | 1=EW_GREEN | 2=ALL_RED
+
+# ---------------------------------------------------------------------------
+# Tasks
+# ---------------------------------------------------------------------------
+tasks:
+  - id: basic_flow
+    name: Basic Traffic Flow Management
+    difficulty: easy
+    description: >
+      Optimise vehicle throughput at a 4-way intersection with moderate,
+      consistent traffic and no emergency vehicles.
+    max_steps: 200
+    grading:
+      throughput_weight: 0.60
+      efficiency_weight: 0.40
+      target_throughput_per_step: 1.8
+
+  - id: emergency_priority
+    name: Emergency Vehicle Prioritisation
+    difficulty: medium
+    description: >
+      Manage mixed traffic while prioritising occasional emergency vehicles
+      that arrive from random directions with high urgency.
+    max_steps: 300
+    grading:
+      throughput_weight:  0.30
+      emergency_weight:   0.35
+      delay_weight:       0.20
+      efficiency_weight:  0.15
+      target_emergency_delay_steps: 3
+
+  - id: dynamic_scenarios
+    name: Dynamic and Complex Scenarios
+    difficulty: hard
+    description: >
+      Handle high traffic density, traffic-surge events, and multiple
+      simultaneous emergency vehicles. Robustness and collision avoidance
+      are critical evaluation criteria.
+    max_steps: 400
+    grading:
+      throughput_weight:    0.25
+      emergency_weight:     0.30
+      delay_weight:         0.20
+      efficiency_weight:    0.15
+      adaptability_weight:  0.10
+
+# ---------------------------------------------------------------------------
+# Server
+# ---------------------------------------------------------------------------
+server:
+  port: 8000
+  module: traffic_control.server.app
+  app: app
+  workers: 2
+
+# ---------------------------------------------------------------------------
+# Docker
+# ---------------------------------------------------------------------------
+docker:
+  base_image: python:3.11-slim
+  exposed_port: 8000

openenv_traffic_control.egg-info/PKG-INFO

@@ -0,0 +1,272 @@
+Metadata-Version: 2.4
+Name: openenv-traffic-control
+Version: 1.0.0
+Summary: Autonomous Traffic Control RL Environment – OpenEnv Hackathon
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: openenv-core[core]>=0.2.2
+Requires-Dist: openai>=1.0.0
+Requires-Dist: gradio>=4.0.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: httpx>=0.25.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+
+---
+title: Traffic Control Environment Server
+emoji: 🎯
+colorFrom: gray
+colorTo: gray
+sdk: docker
+pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
+---
+
+# Traffic Control 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 Traffic Control environment is through the `TrafficControlEnv` class:
+
+```python
+from traffic_control import TrafficControlAction, TrafficControlEnv
+
+try:
+    # Create environment from Docker image
+    traffic_controlenv = TrafficControlEnv.from_docker_image("traffic_control-env:latest")
+
+    # Reset
+    result = traffic_controlenv.reset()
+    print(f"Reset: {result.observation.echoed_message}")
+
+    # Send multiple messages
+    messages = ["Hello, World!", "Testing echo", "Final message"]
+
+    for msg in messages:
+        result = traffic_controlenv.step(TrafficControlAction(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
+    traffic_controlenv.close()
+```
+
+That's it! The `TrafficControlEnv.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 traffic_control-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
+**TrafficControlAction**: Contains a single field
+- `message` (str) - The message to echo back
+
+### Observation
+**TrafficControlObservation**: 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 Traffic Control environment server running, you can connect directly:
+
+```python
+from traffic_control import TrafficControlEnv
+
+# Connect to existing server
+traffic_controlenv = TrafficControlEnv(base_url="<ENV_HTTP_URL_HERE>")
+
+# Use as normal
+result = traffic_controlenv.reset()
+result = traffic_controlenv.step(TrafficControlAction(message="Hello!"))
+```
+
+Note: When connecting to an existing server, `traffic_controlenv.close()` will NOT stop the server.
+
+### Using the Context Manager
+
+The client supports context manager usage for automatic connection management:
+
+```python
+from traffic_control import TrafficControlAction, TrafficControlEnv
+
+# Connect with context manager (auto-connects and closes)
+with TrafficControlEnv(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(TrafficControlAction(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(
+    TrafficControlEnvironment,  # Pass class, not instance
+    TrafficControlAction,
+    TrafficControlObservation,
+    max_concurrent_envs=4,  # Allow 4 concurrent sessions
+)
+```
+
+Then multiple clients can connect simultaneously:
+
+```python
+from traffic_control import TrafficControlAction, TrafficControlEnv
+from concurrent.futures import ThreadPoolExecutor
+
+def run_episode(client_id: int):
+    with TrafficControlEnv(base_url="http://localhost:8000") as env:
+        result = env.reset()
+        for i in range(10):
+            result = env.step(TrafficControlAction(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/traffic_control_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
+
+```
+traffic_control/
+├── .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              # TrafficControlEnv client
+├── models.py              # Action and Observation models
+└── server/
+    ├── __init__.py        # Server module exports
+    ├── traffic_control_environment.py  # Core environment logic
+    ├── app.py             # FastAPI application (HTTP + WebSocket endpoints)
+    └── Dockerfile         # Container image definition
+```

openenv_traffic_control.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+./__init__.py
+./client.py
+./models.py
+openenv_traffic_control.egg-info/PKG-INFO
+openenv_traffic_control.egg-info/SOURCES.txt
+openenv_traffic_control.egg-info/dependency_links.txt
+openenv_traffic_control.egg-info/entry_points.txt
+openenv_traffic_control.egg-info/requires.txt
+openenv_traffic_control.egg-info/top_level.txt
+server/__init__.py
+server/app.py
+server/traffic_control_environment.py

openenv_traffic_control.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

openenv_traffic_control.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+server = traffic_control.server.app:main

openenv_traffic_control.egg-info/requires.txt

@@ -0,0 +1,10 @@
+openenv-core[core]>=0.2.2
+openai>=1.0.0
+gradio>=4.0.0
+numpy>=1.24.0
+python-dotenv>=1.0.0
+
+[dev]
+pytest>=7.4.0
+httpx>=0.25.0
+pytest-asyncio>=0.23.0

openenv_traffic_control.egg-info/top_level.txt

@@ -0,0 +1 @@
+traffic_control

pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-traffic-control"
+version = "1.0.0"
+description = "Autonomous Traffic Control RL Environment - OpenEnv Hackathon"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = [
+    "openenv-core[core]>=0.2.2",
+    "openai>=1.0.0",
+    "gradio>=4.0.0",
+    "numpy>=1.24.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "httpx>=0.25.0",
+    "pytest-asyncio>=0.23.0",
+]
+
+[project.scripts]
+server = "traffic_control.server.app:main"
+
+# ── Setuptools config ──────────────────────────────────────────────────────
+# pyproject.toml lives in  openv/traffic_control/
+# The Python package  traffic_control/  lives one level UP at  openv/
+# so we point package-dir to the parent.
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = [".."]
+include = ["traffic_control*"]

server/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=traffic_control
+
+# 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"
+
+# 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"]

server/__init__.py

@@ -0,0 +1,5 @@
+"""Server package for the Traffic Control environment."""
+
+from .app import app, main
+
+__all__ = ["app", "main"]

server/app.py

@@ -0,0 +1,206 @@
+"""
+FastAPI app for the Autonomous Traffic Control OpenEnv environment.
+
+Endpoints provided automatically by openenv-core create_app():
+  POST /reset    – start a new episode
+  POST /step     – execute one action
+  GET  /state    – episode-level cumulative state
+  GET  /schema   – action / observation JSON schemas
+  WS   /ws       – WebSocket for persistent sessions
+  GET  /health   – liveness probe
+  GET  /docs     – Swagger UI
+
+Custom endpoints added here:
+  POST /grade    – run the automated task grader (returns 0-1 score)
+  GET  /ui       – Gradio testing interface
+
+Usage:
+    # From traffic_control/ directory:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000 --reload
+    python -m traffic_control.server.app
+"""
+
+from __future__ import annotations
+
+import sys
+import os
+
+# Ensure this package's parent is on sys.path so relative package imports work
+# regardless of from where uvicorn is invoked.
+_PKG_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))  # traffic_control/
+_ROOT    = os.path.dirname(_PKG_DIR)                                      # openv/
+for _p in (_PKG_DIR, _ROOT):
+    if _p not in sys.path:
+        sys.path.insert(0, _p)
+
+from openenv.core.env_server.http_server import create_app
+from fastapi import Request
+
+# All imports from within traffic_control/ only
+from traffic_control.models import TrafficAction, TrafficObservation
+from traffic_control.environment import TrafficControlEnvironment
+from traffic_control.tasks import grade as run_grader
+
+
+# ---------------------------------------------------------------------------
+# 1. Standard OpenEnv app
+# ---------------------------------------------------------------------------
+
+app = create_app(
+    TrafficControlEnvironment,
+    TrafficAction,
+    TrafficObservation,
+    env_name="traffic_control",
+    max_concurrent_envs=4,
+)
+
+
+# ---------------------------------------------------------------------------
+# 2. /grade endpoint
+# ---------------------------------------------------------------------------
+
+@app.post("/grade", tags=["eval"])
+async def grade(request: Request):
+    """
+    Run the automated grader for the environment's current state.
+
+    Body (all optional):
+        task_id, total_vehicles_passed, total_emergency_passed,
+        total_waiting_time, total_collisions, total_emergency_delay,
+        total_phase_changes, step_count
+    """
+    body = {}
+    try:
+        body = await request.json()
+    except Exception:
+        pass
+
+    task_id               = body.get("task_id", "basic_flow")
+    total_vehicles        = int(body.get("total_vehicles_passed", 0))
+    total_emergency       = int(body.get("total_emergency_passed", 0))
+    total_waiting         = float(body.get("total_waiting_time", 0.0))
+    total_collisions      = int(body.get("total_collisions", 0))
+    total_emergency_delay = float(body.get("total_emergency_delay", 0.0))
+    total_phase_changes   = int(body.get("total_phase_changes", 0))
+    step_count            = int(body.get("step_count", 1))
+
+    result = run_grader(
+        task_id,
+        total_vehicles_passed=total_vehicles,
+        total_emergency_passed=total_emergency,
+        total_waiting_time=total_waiting,
+        total_collisions=total_collisions,
+        total_emergency_delay=total_emergency_delay,
+        total_phase_changes=total_phase_changes,
+        step_count=step_count,
+    )
+
+    return {
+        "task_id":  task_id,
+        "score":    result.score,
+        "metrics":  result.metrics,
+        "feedback": result.feedback,
+    }
+
+
+# ---------------------------------------------------------------------------
+# 3. Gradio UI (mounted at /ui)
+# ---------------------------------------------------------------------------
+
+try:
+    import gradio as gr
+    import requests as _req
+
+    # Use SERVER_PORT env var (default 8000) so the UI works on any port
+    _PORT = int(os.environ.get("PORT", os.environ.get("SERVER_PORT", "8000")))
+    _SELF_BASE = f"http://127.0.0.1:{_PORT}"
+
+    def _reset_env(task_id: str):
+        try:
+            r = _req.post(
+                f"{_SELF_BASE}/reset",
+                json={"task_id": task_id, "seed": 42},
+                timeout=10,
+            )
+            return r.json() if r.status_code == 200 else {"error": r.text}
+        except Exception as exc:
+            return {"error": str(exc)}
+
+    def _step_env(phase: str):
+        try:
+            # openenv-core wraps the action under an "action" key
+            r = _req.post(
+                f"{_SELF_BASE}/step",
+                json={"action": {"light_phase": int(phase)}},
+                timeout=10,
+            )
+            return r.json() if r.status_code == 200 else {"error": r.text}
+        except Exception as exc:
+            return {"error": str(exc)}
+
+    def _get_state():
+        try:
+            r = _req.get(f"{_SELF_BASE}/state", timeout=10)
+            return r.json() if r.status_code == 200 else {"error": r.text}
+        except Exception as exc:
+            return {"error": str(exc)}
+
+    with gr.Blocks(title="Traffic Control UI") as _ui:
+        gr.Markdown("# 🚦 Autonomous Traffic Control — Testing UI")
+        gr.Markdown("Interact with the OpenEnv HTTP API live.")
+
+        with gr.Row():
+            _task = gr.Dropdown(
+                choices=["basic_flow", "emergency_priority", "dynamic_scenarios"],
+                value="basic_flow",
+                label="Task ID",
+            )
+            _reset_btn = gr.Button("🔄 Reset")
+            _state_btn = gr.Button("📊 State")
+
+        with gr.Row():
+            _phase = gr.Radio(
+                choices=[("0 – NS Green", "0"), ("1 – EW Green", "1"), ("2 – All Red", "2")],
+                value="0",
+                label="Next Action (Light Phase)",
+            )
+            _step_btn = gr.Button("▶️ Step", variant="primary")
+
+        _out = gr.JSON(label="API Response")
+
+        _reset_btn.click(_reset_env, inputs=[_task],  outputs=[_out])
+        _step_btn.click(_step_env,  inputs=[_phase],  outputs=[_out])
+        _state_btn.click(_get_state,                  outputs=[_out])
+
+    app = gr.mount_gradio_app(app, _ui, path="/ui")
+
+except ImportError:
+    # Gradio is optional; server still works without it
+    pass
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    """Entry point: start uvicorn server. Reads --host and --port from CLI args."""
+    import argparse
+    import uvicorn
+
+    parser = argparse.ArgumentParser(description="Traffic Control OpenEnv Server")
+    parser.add_argument("--host", default=os.environ.get("HOST", "0.0.0.0"))
+    parser.add_argument("--port", type=int, default=int(os.environ.get("PORT", "8000")))
+    parser.add_argument("--workers", type=int, default=1)
+    args, _ = parser.parse_known_args()  # ignore unknown args from uv
+
+    uvicorn.run(
+        "traffic_control.server.app:app",
+        host=args.host,
+        port=args.port,
+        workers=args.workers,
+    )
+
+
+if __name__ == "__main__":
+    main()

server/requirements.txt

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

server/traffic_control_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.
+
+"""
+Traffic Control 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 TrafficControlAction, TrafficControlObservation
+except ImportError:
+    from models import TrafficControlAction, TrafficControlObservation
+
+
+class TrafficControlEnvironment(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 = TrafficControlEnvironment()
+        >>> obs = env.reset()
+        >>> print(obs.echoed_message)  # "Traffic Control environment ready!"
+        >>>
+        >>> obs = env.step(TrafficControlAction(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 traffic_control environment."""
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count = 0
+
+    def reset(self) -> TrafficControlObservation:
+        """
+        Reset the environment.
+
+        Returns:
+            TrafficControlObservation with a ready message
+        """
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count += 1
+
+        return TrafficControlObservation(
+            echoed_message="Traffic Control environment ready!",
+            message_length=0,
+            done=False,
+            reward=0.0,
+        )
+
+    def step(self, action: TrafficControlAction) -> TrafficControlObservation:  # type: ignore[override]
+        """
+        Execute a step in the environment by echoing the message.
+
+        Args:
+            action: TrafficControlAction containing the message to echo
+
+        Returns:
+            TrafficControlObservation 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 TrafficControlObservation(
+            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

tasks.py

@@ -0,0 +1,226 @@
+"""
+Task graders for the Autonomous Traffic Control OpenEnv environment.
+
+Defines three tasks of increasing difficulty:
+  1. basic_flow          – baseline throughput optimisation (Easy)
+  2. emergency_priority  – emergency vehicle management + throughput (Medium)
+  3. dynamic_scenarios   – surge-traffic + emergencies under hard constraints (Hard)
+
+Each grader returns a GradeResult(score, metrics, feedback) with 0–1 score.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict
+
+
+@dataclass
+class GradeResult:
+    """Standardised grading result."""
+    score: float                        # strictly in (0.001, 0.999)
+    metrics: Dict[str, Any] = field(default_factory=dict)
+    feedback: str = ""
+
+
+def _clamp(score: float) -> float:
+    """Ensure score is strictly between 0 and 1 (never 0.0 or 1.0 exactly)."""
+    return round(max(0.001, min(0.999, score)), 4)
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+def grade(
+    task_id: str,
+    *,
+    total_vehicles_passed: int   = 0,
+    total_emergency_passed: int  = 0,
+    total_waiting_time: float    = 0.0,
+    total_collisions: int        = 0,
+    total_emergency_delay: float = 0.0,
+    total_phase_changes: int     = 0,
+    step_count: int              = 1,
+) -> GradeResult:
+    """Route to the appropriate task grader."""
+    graders = {
+        "basic_flow":         _grade_basic_flow,
+        "emergency_priority": _grade_emergency_priority,
+        "dynamic_scenarios":  _grade_dynamic_scenarios,
+    }
+    if task_id not in graders:
+        return GradeResult(
+            score=0.001,
+            feedback=f"Unknown task_id '{task_id}'. Valid: {list(graders.keys())}",
+        )
+    return graders[task_id](
+        total_vehicles_passed=total_vehicles_passed,
+        total_emergency_passed=total_emergency_passed,
+        total_waiting_time=total_waiting_time,
+        total_collisions=total_collisions,
+        total_emergency_delay=total_emergency_delay,
+        total_phase_changes=total_phase_changes,
+        step_count=max(step_count, 1),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Task 1 – Basic Flow  (Easy)
+# ---------------------------------------------------------------------------
+
+_BASIC_FLOW_TARGET_THROUGHPUT_PER_STEP = 1.8  # vehicles/step considered "perfect"
+
+
+def _grade_basic_flow(
+    *,
+    total_vehicles_passed: int,
+    total_waiting_time: float,
+    total_collisions: int,
+    step_count: int,
+    **_ignored,
+) -> GradeResult:
+    throughput_per_step = total_vehicles_passed / step_count
+    throughput_score    = min(throughput_per_step / _BASIC_FLOW_TARGET_THROUGHPUT_PER_STEP, 1.0)
+    efficiency_score    = 1.0 / (1.0 + total_waiting_time / max(step_count, 1) * 0.1)
+    collision_penalty   = 0.8 if total_collisions > 0 else 0.0
+
+    raw   = throughput_score * 0.6 + efficiency_score * 0.4
+    score = max(0.0, raw - collision_penalty)
+
+    return GradeResult(
+        score=_clamp(raw - collision_penalty),
+        metrics={
+            "throughput_per_step": round(throughput_per_step, 3),
+            "throughput_score":    round(throughput_score,    4),
+            "efficiency_score":    round(efficiency_score,    4),
+            "total_collisions":    total_collisions,
+            "collision_penalty":   collision_penalty,
+        },
+        feedback=(
+            f"Throughput {throughput_per_step:.2f} veh/step "
+            f"(target {_BASIC_FLOW_TARGET_THROUGHPUT_PER_STEP}). "
+            + ("⚠ Collision penalty applied!" if total_collisions else "No collisions ✓.")
+        ),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Task 2 – Emergency Priority  (Medium)
+# ---------------------------------------------------------------------------
+
+_EMERG_TARGET_DELAY_PER_VEHICLE = 3.0  # steps/emergency vehicle
+
+
+def _grade_emergency_priority(
+    *,
+    total_vehicles_passed: int,
+    total_emergency_passed: int,
+    total_waiting_time: float,
+    total_collisions: int,
+    total_emergency_delay: float,
+    step_count: int,
+    **_ignored,
+) -> GradeResult:
+    throughput_per_step = total_vehicles_passed / step_count
+    throughput_score    = min(throughput_per_step / 1.5, 1.0)
+
+    # Emergency throughput score: 1.0 if ≥ 1 emergency vehicle cleared per 20 steps
+    em_rate       = total_emergency_passed / step_count
+    em_rate_score = min(em_rate / (1.0 / 20.0), 1.0)
+
+    # Emergency delay score
+    if total_emergency_passed > 0:
+        avg_delay   = total_emergency_delay / total_emergency_passed
+        delay_score = max(0.0, 1.0 - avg_delay / (_EMERG_TARGET_DELAY_PER_VEHICLE * 4))
+    else:
+        delay_score = 0.5
+
+    efficiency_score  = 1.0 / (1.0 + total_waiting_time / max(step_count, 1) * 0.05)
+    collision_penalty = 0.85 if total_collisions > 0 else 0.0
+
+    raw   = (throughput_score * 0.30 + em_rate_score * 0.35 +
+             delay_score      * 0.20 + efficiency_score * 0.15)
+    score = max(0.0, raw - collision_penalty)
+
+    avg_delay_str = (
+        f"{total_emergency_delay / total_emergency_passed:.1f} steps"
+        if total_emergency_passed else "N/A"
+    )
+
+    return GradeResult(
+        score=_clamp(raw - collision_penalty),
+        metrics={
+            "throughput_per_step":       round(throughput_per_step, 3),
+            "throughput_score":          round(throughput_score,    4),
+            "emergency_rate_score":      round(em_rate_score,       4),
+            "emergency_delay_score":     round(delay_score,         4),
+            "efficiency_score":          round(efficiency_score,    4),
+            "total_emergency_passed":    total_emergency_passed,
+            "avg_emergency_delay_steps": avg_delay_str,
+            "total_collisions":          total_collisions,
+        },
+        feedback=(
+            f"Cleared {total_emergency_passed} emergency vehicles "
+            f"(avg delay {avg_delay_str}). "
+            f"Throughput {throughput_per_step:.2f} veh/step. "
+            + ("⚠ Collision!" if total_collisions else "No collisions ✓.")
+        ),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Task 3 – Dynamic Scenarios  (Hard)
+# ---------------------------------------------------------------------------
+
+def _grade_dynamic_scenarios(
+    *,
+    total_vehicles_passed: int,
+    total_emergency_passed: int,
+    total_waiting_time: float,
+    total_collisions: int,
+    total_emergency_delay: float,
+    total_phase_changes: int,
+    step_count: int,
+    **_ignored,
+) -> GradeResult:
+    throughput_per_step = total_vehicles_passed / step_count
+    throughput_score    = min(throughput_per_step / 2.0, 1.0)
+
+    em_rate       = total_emergency_passed / step_count
+    em_rate_score = min(em_rate / (1.0 / 15.0), 1.0)
+
+    if total_emergency_passed > 0:
+        avg_delay   = total_emergency_delay / total_emergency_passed
+        delay_score = max(0.0, 1.0 - avg_delay / 5.0)
+    else:
+        delay_score = 0.0
+
+    efficiency_score   = 1.0 / (1.0 + total_waiting_time / max(step_count, 1) * 0.08)
+    adaptability_score = 1.0 / (1.0 + total_phase_changes / max(step_count, 1) * 0.5)
+    collision_penalty  = 0.9 if total_collisions > 0 else 0.0
+
+    raw   = (throughput_score    * 0.25 + em_rate_score   * 0.30 +
+             delay_score         * 0.20 + efficiency_score * 0.15 +
+             adaptability_score  * 0.10)
+    score = max(0.0, raw - collision_penalty)
+
+    return GradeResult(
+        score=_clamp(raw - collision_penalty),
+        metrics={
+            "throughput_per_step":   round(throughput_per_step, 3),
+            "throughput_score":      round(throughput_score,    4),
+            "emergency_rate_score":  round(em_rate_score,       4),
+            "emergency_delay_score": round(delay_score,         4),
+            "efficiency_score":      round(efficiency_score,    4),
+            "adaptability_score":    round(adaptability_score,  4),
+            "total_collisions":      total_collisions,
+            "total_phase_changes":   total_phase_changes,
+        },
+        feedback=(
+            f"Dynamic task: throughput {throughput_per_step:.2f} veh/step, "
+            f"{total_emergency_passed} emergencies cleared, "
+            f"{total_phase_changes} phase changes over {step_count} steps. "
+            + ("⚠ Collision!" if total_collisions else "No collisions ✓.")
+        ),
+    )