Upload folder using huggingface_hub

.gitattributes

@@ -33,3 +33,207 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+test_images/img_000_ep1_step0.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_001_ep1_step1.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_002_ep1_step2.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_003_ep1_step3.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_004_ep1_step4.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_005_ep1_step5.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_006_ep1_step6.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_007_ep1_step7.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_008_ep1_step8.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_009_ep1_step9.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_010_ep1_step10.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_011_ep1_step11.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_012_ep1_step12.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_013_ep1_step13.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_014_ep1_step14.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_015_ep1_step15.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_016_ep1_step16.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_017_ep1_step17.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_018_ep1_step18.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_019_ep1_step19.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_020_ep1_step20.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_021_ep1_step21.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_022_ep1_step22.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_023_ep1_step23.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_024_ep1_step24.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_025_ep1_step25.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_026_ep1_step26.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_027_ep1_step27.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_028_ep1_step28.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_029_ep1_step29.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_030_ep1_step30.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_031_ep1_step31.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_032_ep1_step32.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_033_ep1_step33.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_034_ep1_step34.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_035_ep1_step35.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_036_ep1_step36.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_037_ep1_step37.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_038_ep1_step38.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_039_ep1_step39.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_040_ep1_step40.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_041_ep1_step41.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_042_ep1_step42.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_043_ep1_step43.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_044_ep1_step44.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_045_ep1_step45.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_046_ep1_step46.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_047_ep1_step47.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_048_ep1_step48.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_049_ep1_step49.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_050_ep1_step50.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_051_ep1_step51.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_052_ep1_step52.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_053_ep1_step53.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_054_ep1_step54.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_055_ep1_step55.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_056_ep1_step56.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_057_ep1_step57.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_058_ep1_step58.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_059_ep1_step59.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_060_ep1_step60.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_061_ep1_step61.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_062_ep1_step62.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_063_ep1_step63.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_064_ep1_step64.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_065_ep1_step65.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_066_ep1_step66.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_067_ep1_step67.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_068_ep1_step68.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_069_ep1_step69.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_070_ep1_step70.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_071_ep2_step0.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_072_ep2_step1.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_073_ep2_step2.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_074_ep2_step3.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_075_ep2_step4.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_076_ep2_step5.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_077_ep2_step6.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_078_ep2_step7.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_079_ep2_step8.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_080_ep2_step9.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_081_ep2_step10.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_082_ep2_step11.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_083_ep2_step12.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_084_ep2_step13.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_085_ep2_step14.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_086_ep2_step15.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_087_ep2_step16.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_088_ep2_step17.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_089_ep2_step18.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_090_ep2_step19.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_091_ep2_step20.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_092_ep2_step21.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_093_ep2_step22.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_094_ep2_step23.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_095_ep2_step24.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_096_ep2_step25.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_097_ep2_step26.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_098_ep2_step27.png filter=lfs diff=lfs merge=lfs -text
+test_images/img_099_ep2_step28.png filter=lfs diff=lfs merge=lfs -text
+test_images/traffic_demo.gif filter=lfs diff=lfs merge=lfs -text
+test_images/traffic_demo.mp4 filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_000_ep1_step0.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_001_ep1_step1.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_002_ep1_step2.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_003_ep1_step3.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_004_ep1_step4.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_005_ep1_step5.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_006_ep1_step6.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_007_ep1_step7.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_008_ep1_step8.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_009_ep1_step9.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_010_ep1_step10.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_011_ep1_step11.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_012_ep1_step12.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_013_ep1_step13.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_014_ep1_step14.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_015_ep1_step15.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_016_ep1_step16.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_017_ep1_step17.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_018_ep1_step18.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_019_ep1_step19.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_020_ep1_step20.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_021_ep1_step21.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_022_ep1_step22.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_023_ep1_step23.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_024_ep1_step24.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_025_ep1_step25.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_026_ep1_step26.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_027_ep1_step27.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_028_ep1_step28.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_029_ep1_step29.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_030_ep1_step30.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_031_ep1_step31.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_032_ep1_step32.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_033_ep1_step33.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_034_ep1_step34.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_035_ep1_step35.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_036_ep1_step36.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_037_ep1_step37.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_038_ep1_step38.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_039_ep1_step39.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_040_ep1_step40.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_041_ep1_step41.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_042_ep1_step42.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_043_ep1_step43.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_044_ep1_step44.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_045_ep1_step45.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_046_ep1_step46.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_047_ep1_step47.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_048_ep1_step48.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_049_ep1_step49.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_050_ep1_step50.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_051_ep1_step51.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_052_ep1_step52.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_053_ep1_step53.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_054_ep1_step54.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_055_ep1_step55.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_056_ep1_step56.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_057_ep1_step57.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_058_ep1_step58.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_059_ep1_step59.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_060_ep1_step60.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_061_ep1_step61.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_062_ep1_step62.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_063_ep1_step63.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_064_ep1_step64.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_065_ep1_step65.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_066_ep1_step66.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_067_ep1_step67.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_068_ep1_step68.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_069_ep1_step69.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_070_ep1_step70.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_071_ep1_step71.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_072_ep1_step72.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_073_ep1_step73.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_074_ep1_step74.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_075_ep1_step75.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_076_ep1_step76.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_077_ep1_step77.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_078_ep1_step78.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_079_ep1_step79.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_080_ep1_step80.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_081_ep1_step81.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_082_ep1_step82.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_083_ep1_step83.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_084_ep1_step84.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_085_ep1_step85.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_086_ep1_step86.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_087_ep1_step87.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_088_ep1_step88.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_089_ep1_step89.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_090_ep1_step90.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_091_ep2_step0.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_092_ep2_step1.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_093_ep2_step2.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_094_ep2_step3.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_095_ep2_step4.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_096_ep2_step5.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_097_ep2_step6.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_098_ep2_step7.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/img_099_ep2_step8.png filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/traffic_demo_dijkstra.gif filter=lfs diff=lfs merge=lfs -text
+test_images_dijkstra/traffic_demo_dijkstra.mp4 filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,81 @@
+# 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=road_traffic_simulator_env
+
+# 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
+ENV ENABLE_WEB_INTERFACE=true
+CMD ["sh", "-c", "cd /app/env && uvicorn server.app:app --host 0.0.0.0 --port 8000"]

README.md

@@ -1,10 +1,255 @@
 ---
-title: Road Traffic Simulator Env
-emoji: 📊
-colorFrom: indigo
-colorTo: red
+title: Road Traffic Simulator Env Environment Server
+emoji: 🖲️
+colorFrom: purple
+colorTo: green
 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
+# Road Traffic Simulator 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 Road Traffic Simulator Env environment is through the `RoadTrafficSimulatorEnv` class:
+
+```python
+from road_traffic_simulator_env import RoadTrafficSimulatorAction, RoadTrafficSimulatorEnv
+
+try:
+    # Create environment from Docker image
+    road_traffic_simulator_envenv = RoadTrafficSimulatorEnv.from_docker_image("road_traffic_simulator_env-env:latest")
+
+    # Reset
+    result = road_traffic_simulator_envenv.reset()
+    print(f"Reset: {result.observation.echoed_message}")
+
+    # Send multiple messages
+    messages = ["Hello, World!", "Testing echo", "Final message"]
+
+    for msg in messages:
+        result = road_traffic_simulator_envenv.step(RoadTrafficSimulatorAction(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
+    road_traffic_simulator_envenv.close()
+```
+
+That's it! The `RoadTrafficSimulatorEnv.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 road_traffic_simulator_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
+**RoadTrafficSimulatorAction**: Contains a single field
+- `message` (str) - The message to echo back
+
+### Observation
+**RoadTrafficSimulatorObservation**: 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 Road Traffic Simulator Env environment server running, you can connect directly:
+
+```python
+from road_traffic_simulator_env import RoadTrafficSimulatorEnv
+
+# Connect to existing server
+road_traffic_simulator_envenv = RoadTrafficSimulatorEnv(base_url="<ENV_HTTP_URL_HERE>")
+
+# Use as normal
+result = road_traffic_simulator_envenv.reset()
+result = road_traffic_simulator_envenv.step(RoadTrafficSimulatorAction(message="Hello!"))
+```
+
+Note: When connecting to an existing server, `road_traffic_simulator_envenv.close()` will NOT stop the server.
+
+### Using the Context Manager
+
+The client supports context manager usage for automatic connection management:
+
+```python
+from road_traffic_simulator_env import RoadTrafficSimulatorAction, RoadTrafficSimulatorEnv
+
+# Connect with context manager (auto-connects and closes)
+with RoadTrafficSimulatorEnv(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(RoadTrafficSimulatorAction(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(
+    RoadTrafficSimulatorEnvironment,  # Pass class, not instance
+    RoadTrafficSimulatorAction,
+    RoadTrafficSimulatorObservation,
+    max_concurrent_envs=4,  # Allow 4 concurrent sessions
+)
+```
+
+Then multiple clients can connect simultaneously:
+
+```python
+from road_traffic_simulator_env import RoadTrafficSimulatorAction, RoadTrafficSimulatorEnv
+from concurrent.futures import ThreadPoolExecutor
+
+def run_episode(client_id: int):
+    with RoadTrafficSimulatorEnv(base_url="http://localhost:8000") as env:
+        result = env.reset()
+        for i in range(10):
+            result = env.step(RoadTrafficSimulatorAction(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/road_traffic_simulator_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
+
+```
+road_traffic_simulator_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              # RoadTrafficSimulatorEnv client
+├── models.py              # Action and Observation models
+└── server/
+    ├── __init__.py        # Server module exports
+    ├── road_traffic_simulator_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.
+
+"""Road Traffic Simulator Env Environment."""
+
+from .client import RoadTrafficSimulatorEnv
+from .models import RoadTrafficSimulatorAction, RoadTrafficSimulatorObservation
+
+__all__ = [
+    "RoadTrafficSimulatorAction",
+    "RoadTrafficSimulatorObservation",
+    "RoadTrafficSimulatorEnv",
+]

client.py

@@ -0,0 +1,84 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Road Traffic Simulator Environment Client."""
+
+from typing import Dict
+
+from openenv.core.client_types import StepResult
+from openenv.core.env_server.types import State
+from openenv.core import EnvClient
+
+from .models import RoadTrafficSimulatorAction, RoadTrafficSimulatorObservation
+
+
+class RoadTrafficSimulatorEnv(
+    EnvClient[RoadTrafficSimulatorAction, RoadTrafficSimulatorObservation]
+):
+    """
+    Client for the Road Traffic Simulator Environment.
+
+    The agent controls a single car navigating from a random start to a random
+    end node in downtown San Francisco, surrounded by background traffic.
+
+    Action space
+    ------------
+    RoadTrafficSimulatorAction(next_edge_index=<int>)
+        Choose which outgoing road to take at the current intersection.
+        Valid range: [0, observation.available_actions - 1].
+
+    Observation
+    -----------
+    RoadTrafficSimulatorObservation
+        .lat / .lon              – agent GPS position
+        .goal_lat / .goal_lon    – destination GPS position
+        .distance_to_goal        – straight-line metres to goal
+        .available_actions       – number of choices at current node
+        .map_screenshot          – base64 PNG (400×400) traffic heatmap
+
+    Example
+    -------
+    >>> with RoadTrafficSimulatorEnv(base_url="http://localhost:8000") as env:
+    ...     result = env.reset()
+    ...     obs = result.observation
+    ...     print(f"Start: ({obs.lat:.4f}, {obs.lon:.4f})")
+    ...     print(f"Goal:  ({obs.goal_lat:.4f}, {obs.goal_lon:.4f})")
+    ...     print(f"Dist:  {obs.distance_to_goal:.0f} m")
+    ...
+    ...     # Greedy: always pick edge 0
+    ...     while not result.done:
+    ...         result = env.step(RoadTrafficSimulatorAction(next_edge_index=0))
+    ...     print(f"Done after {result.observation.metadata['step']} steps")
+    """
+
+    def _step_payload(self, action: RoadTrafficSimulatorAction) -> Dict:
+        return {"next_edge_index": action.next_edge_index}
+
+    def _parse_result(self, payload: Dict) -> StepResult[RoadTrafficSimulatorObservation]:
+        obs_data = payload.get("observation", {})
+        observation = RoadTrafficSimulatorObservation(
+            lat=obs_data.get("lat", 0.0),
+            lon=obs_data.get("lon", 0.0),
+            goal_lat=obs_data.get("goal_lat", 0.0),
+            goal_lon=obs_data.get("goal_lon", 0.0),
+            distance_to_goal=obs_data.get("distance_to_goal", 0.0),
+            available_actions=obs_data.get("available_actions", 1),
+            map_screenshot=obs_data.get("map_screenshot", ""),
+            done=payload.get("done", False),
+            reward=payload.get("reward"),
+            metadata=obs_data.get("metadata", {}),
+        )
+        return StepResult(
+            observation=observation,
+            reward=payload.get("reward"),
+            done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: Dict) -> State:
+        return State(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+        )

index.html

@@ -0,0 +1,613 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>San Francisco Traffic Simulator</title>
+    <link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" />
+    <script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>
+    <style>
+        * {
+            margin: 0;
+            padding: 0;
+            box-sizing: border-box;
+        }
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+        }
+        #map {
+            width: 100vw;
+            height: 100vh;
+        }
+        .controls {
+            position: absolute;
+            top: 10px;
+            right: 10px;
+            z-index: 1000;
+            background: white;
+            padding: 15px;
+            border-radius: 8px;
+            box-shadow: 0 2px 10px rgba(0,0,0,0.2);
+            min-width: 220px;
+        }
+        .controls h3 {
+            margin-bottom: 10px;
+            color: #333;
+        }
+        .controls button {
+            padding: 8px 16px;
+            margin: 5px;
+            border: none;
+            border-radius: 4px;
+            cursor: pointer;
+            font-size: 14px;
+        }
+        .controls button.primary {
+            background: #007bff;
+            color: white;
+        }
+        .controls button.secondary {
+            background: #6c757d;
+            color: white;
+        }
+        .controls button:hover {
+            opacity: 0.9;
+        }
+        .controls button:disabled {
+            opacity: 0.5;
+            cursor: not-allowed;
+        }
+        .stats {
+            margin-top: 10px;
+            font-size: 13px;
+            color: #555;
+        }
+        .stats div {
+            margin: 3px 0;
+        }
+        .legend {
+            position: absolute;
+            bottom: 30px;
+            right: 10px;
+            z-index: 1000;
+            background: white;
+            padding: 10px;
+            border-radius: 8px;
+            box-shadow: 0 2px 10px rgba(0,0,0,0.2);
+        }
+        .legend-item {
+            display: flex;
+            align-items: center;
+            margin: 5px 0;
+            font-size: 12px;
+        }
+        .legend-color {
+            width: 30px;
+            height: 10px;
+            margin-right: 8px;
+            border-radius: 2px;
+        }
+        .loading {
+            position: absolute;
+            top: 50%;
+            left: 50%;
+            transform: translate(-50%, -50%);
+            z-index: 2000;
+            background: rgba(255,255,255,0.95);
+            padding: 30px 50px;
+            border-radius: 10px;
+            box-shadow: 0 4px 20px rgba(0,0,0,0.3);
+            text-align: center;
+        }
+        .loading h2 {
+            margin-bottom: 10px;
+            color: #333;
+        }
+        .loading p {
+            color: #666;
+        }
+        .spinner {
+            width: 40px;
+            height: 40px;
+            border: 4px solid #f3f3f3;
+            border-top: 4px solid #007bff;
+            border-radius: 50%;
+            animation: spin 1s linear infinite;
+            margin: 15px auto;
+        }
+        @keyframes spin {
+            0% { transform: rotate(0deg); }
+            100% { transform: rotate(360deg); }
+        }
+    </style>
+</head>
+<body>
+    <div id="map"></div>
+
+    <div class="loading" id="loading">
+        <h2>Loading Road Network</h2>
+        <div class="spinner"></div>
+        <p id="loadingStatus">Fetching OpenStreetMap data...</p>
+    </div>
+
+    <div class="controls">
+        <h3>Traffic Simulator</h3>
+        <div>
+            <button class="primary" id="startBtn" disabled>Start</button>
+            <button class="secondary" id="resetBtn" disabled>Reset</button>
+        </div>
+        <div class="stats">
+            <div>Agents: <span id="agentCount">10000</span></div>
+            <div>Road Segments: <span id="roadCount">-</span></div>
+            <div>Intersections: <span id="nodeCount">-</span></div>
+            <div>Simulation Speed: <span id="speed">1x</span></div>
+            <input type="range" id="speedSlider" min="1" max="10" value="1" style="width: 100%; margin-top: 5px;">
+        </div>
+    </div>
+
+    <div class="legend">
+        <strong>Traffic Density</strong>
+        <div class="legend-item"><div class="legend-color" style="background: #00ff00;"></div> Low</div>
+        <div class="legend-item"><div class="legend-color" style="background: #ffff00;"></div> Medium</div>
+        <div class="legend-item"><div class="legend-color" style="background: #ff8800;"></div> High</div>
+        <div class="legend-item"><div class="legend-color" style="background: #ff0000;"></div> Congested</div>
+    </div>
+
+    <script>
+        // Initialize map centered on downtown San Francisco
+        const SF_CENTER = [37.7849, -122.4094];
+        const map = L.map('map').setView(SF_CENTER, 16);
+
+        // Add OpenStreetMap tiles
+        L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
+            attribution: '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
+        }).addTo(map);
+
+        // Road network data structures
+        let nodes = {};           // nodeId -> {lat, lng, connections: [edgeIds]}
+        let edges = [];           // {id, startNode, endNode, coords: [[lat,lng],...], length, capacity, wayId}
+        let edgeById = {};        // edgeId -> edge
+        let trafficCount = {};    // edgeId -> count
+        let roadPolylines = {};   // edgeId -> L.polyline
+
+        // Bounding box for downtown SF (small area for faster loading)
+        const BBOX = {
+            south: 37.7800,
+            west: -122.4180,
+            north: 37.7900,
+            east: -122.4020
+        };
+
+        // Fetch road network from Overpass API
+        async function fetchRoadNetwork() {
+            const loadingStatus = document.getElementById('loadingStatus');
+            loadingStatus.textContent = 'Querying OpenStreetMap Overpass API...';
+
+            // Overpass query for roads in the bounding box
+            const query = `
+                [out:json][timeout:30];
+                (
+                    way["highway"~"^(motorway|trunk|primary|secondary|tertiary|residential|unclassified)$"]
+                        (${BBOX.south},${BBOX.west},${BBOX.north},${BBOX.east});
+                );
+                out body;
+                >;
+                out skel qt;
+            `;
+
+            const url = 'https://overpass-api.de/api/interpreter';
+
+            try {
+                const response = await fetch(url, {
+                    method: 'POST',
+                    body: `data=${encodeURIComponent(query)}`,
+                    headers: {
+                        'Content-Type': 'application/x-www-form-urlencoded'
+                    }
+                });
+
+                if (!response.ok) {
+                    throw new Error(`HTTP error! status: ${response.status}`);
+                }
+
+                const data = await response.json();
+                loadingStatus.textContent = 'Processing road network...';
+
+                return data;
+            } catch (error) {
+                console.error('Error fetching OSM data:', error);
+                loadingStatus.textContent = 'Error loading data. Retrying...';
+
+                // Retry once with different server
+                try {
+                    const response = await fetch('https://overpass.kumi.systems/api/interpreter', {
+                        method: 'POST',
+                        body: `data=${encodeURIComponent(query)}`,
+                        headers: {
+                            'Content-Type': 'application/x-www-form-urlencoded'
+                        }
+                    });
+                    const data = await response.json();
+                    return data;
+                } catch (e) {
+                    throw e;
+                }
+            }
+        }
+
+        // Parse OSM data into graph structure
+        function parseOSMData(osmData) {
+            const nodeMap = {};  // OSM node id -> {lat, lng}
+            const ways = [];     // Array of ways with their nodes
+
+            // First pass: collect all nodes
+            osmData.elements.forEach(el => {
+                if (el.type === 'node') {
+                    nodeMap[el.id] = { lat: el.lat, lng: el.lon };
+                }
+            });
+
+            // Second pass: collect ways
+            osmData.elements.forEach(el => {
+                if (el.type === 'way' && el.nodes && el.nodes.length >= 2) {
+                    const highway = el.tags?.highway;
+                    ways.push({
+                        id: el.id,
+                        nodeIds: el.nodes,
+                        highway: highway,
+                        name: el.tags?.name || '',
+                        oneway: el.tags?.oneway === 'yes',
+                        lanes: parseInt(el.tags?.lanes) || 2
+                    });
+                }
+            });
+
+            // Build graph: create edges for each way segment
+            let edgeId = 0;
+            const graphNodes = {};  // Will store unique intersection nodes
+
+            ways.forEach(way => {
+                for (let i = 0; i < way.nodeIds.length - 1; i++) {
+                    const startNodeId = way.nodeIds[i];
+                    const endNodeId = way.nodeIds[i + 1];
+
+                    const startCoord = nodeMap[startNodeId];
+                    const endCoord = nodeMap[endNodeId];
+
+                    if (!startCoord || !endCoord) continue;
+
+                    // Calculate edge length (in meters, approximate)
+                    const length = haversineDistance(
+                        startCoord.lat, startCoord.lng,
+                        endCoord.lat, endCoord.lng
+                    );
+
+                    // Determine capacity based on road type
+                    let capacity = 10;
+                    switch (way.highway) {
+                        case 'motorway': capacity = 50; break;
+                        case 'trunk': capacity = 40; break;
+                        case 'primary': capacity = 30; break;
+                        case 'secondary': capacity = 25; break;
+                        case 'tertiary': capacity = 20; break;
+                        case 'residential': capacity = 15; break;
+                        default: capacity = 10;
+                    }
+                    capacity *= (way.lanes / 2);
+
+                    // Create edge
+                    const edge = {
+                        id: `e${edgeId++}`,
+                        startNode: startNodeId,
+                        endNode: endNodeId,
+                        coords: [[startCoord.lat, startCoord.lng], [endCoord.lat, endCoord.lng]],
+                        length: length,
+                        capacity: Math.max(5, Math.round(capacity)),
+                        wayId: way.id,
+                        highway: way.highway,
+                        oneway: way.oneway
+                    };
+
+                    edges.push(edge);
+                    edgeById[edge.id] = edge;
+                    trafficCount[edge.id] = 0;
+
+                    // Register nodes
+                    if (!graphNodes[startNodeId]) {
+                        graphNodes[startNodeId] = {
+                            id: startNodeId,
+                            lat: startCoord.lat,
+                            lng: startCoord.lng,
+                            outEdges: [],
+                            inEdges: []
+                        };
+                    }
+                    if (!graphNodes[endNodeId]) {
+                        graphNodes[endNodeId] = {
+                            id: endNodeId,
+                            lat: endCoord.lat,
+                            lng: endCoord.lng,
+                            outEdges: [],
+                            inEdges: []
+                        };
+                    }
+
+                    // Add edge connections
+                    graphNodes[startNodeId].outEdges.push(edge.id);
+                    graphNodes[endNodeId].inEdges.push(edge.id);
+
+                    // If not one-way, add reverse connections
+                    if (!way.oneway) {
+                        graphNodes[endNodeId].outEdges.push(edge.id);
+                        graphNodes[startNodeId].inEdges.push(edge.id);
+                    }
+                }
+            });
+
+            nodes = graphNodes;
+
+            console.log(`Parsed ${Object.keys(nodes).length} nodes and ${edges.length} edges`);
+        }
+
+        // Haversine formula to calculate distance between two points
+        function haversineDistance(lat1, lon1, lat2, lon2) {
+            const R = 6371000; // Earth's radius in meters
+            const dLat = (lat2 - lat1) * Math.PI / 180;
+            const dLon = (lon2 - lon1) * Math.PI / 180;
+            const a = Math.sin(dLat/2) * Math.sin(dLat/2) +
+                      Math.cos(lat1 * Math.PI / 180) * Math.cos(lat2 * Math.PI / 180) *
+                      Math.sin(dLon/2) * Math.sin(dLon/2);
+            const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a));
+            return R * c;
+        }
+
+        // Draw roads on map
+        function drawRoads() {
+            edges.forEach(edge => {
+                const polyline = L.polyline(edge.coords, {
+                    color: '#00ff00',
+                    weight: getEdgeWeight(edge),
+                    opacity: 0.8
+                }).addTo(map);
+                roadPolylines[edge.id] = polyline;
+            });
+        }
+
+        // Get line weight based on road type
+        function getEdgeWeight(edge) {
+            switch (edge.highway) {
+                case 'motorway': return 8;
+                case 'trunk': return 7;
+                case 'primary': return 6;
+                case 'secondary': return 5;
+                case 'tertiary': return 4;
+                default: return 3;
+            }
+        }
+
+        // Agent class
+        class Agent {
+            constructor(id) {
+                this.id = id;
+                this.edge = edges[Math.floor(Math.random() * edges.length)];
+                this.progress = Math.random();
+                this.direction = Math.random() < 0.5 ? 1 : -1; // Direction on edge
+                if (this.edge.oneway) this.direction = 1;
+                this.baseSpeed = 0.01 + Math.random() * 0.02;
+            }
+
+            getPosition() {
+                const p = this.direction === 1 ? this.progress : (1 - this.progress);
+                const start = this.edge.coords[0];
+                const end = this.edge.coords[1];
+                return [
+                    start[0] + (end[0] - start[0]) * p,
+                    start[1] + (end[1] - start[1]) * p
+                ];
+            }
+
+            update(speedMultiplier) {
+                // Calculate speed based on traffic density
+                const density = trafficCount[this.edge.id] / this.edge.capacity;
+                const trafficFactor = Math.max(0.05, 1 - density * 0.9);
+
+                // Adjust speed based on edge length (longer edges = slower progress rate)
+                const lengthFactor = 50 / Math.max(20, this.edge.length);
+
+                this.progress += this.baseSpeed * speedMultiplier * trafficFactor * lengthFactor;
+
+                // Move to next edge when reaching end
+                if (this.progress >= 1) {
+                    this.moveToNextEdge();
+                }
+            }
+
+            moveToNextEdge() {
+                this.progress = 0;
+
+                // Find current node (end of current edge based on direction)
+                const currentNodeId = this.direction === 1 ? this.edge.endNode : this.edge.startNode;
+                const node = nodes[currentNodeId];
+
+                if (!node) {
+                    // Teleport to random edge
+                    this.edge = edges[Math.floor(Math.random() * edges.length)];
+                    this.direction = this.edge.oneway ? 1 : (Math.random() < 0.5 ? 1 : -1);
+                    return;
+                }
+
+                // Get available outgoing edges (excluding current edge)
+                let availableEdges = node.outEdges
+                    .map(eid => edgeById[eid])
+                    .filter(e => e && e.id !== this.edge.id);
+
+                if (availableEdges.length === 0) {
+                    // Dead end - reverse direction or teleport
+                    if (!this.edge.oneway) {
+                        this.direction *= -1;
+                        this.progress = 0;
+                    } else {
+                        this.edge = edges[Math.floor(Math.random() * edges.length)];
+                        this.direction = 1;
+                    }
+                    return;
+                }
+
+                // Pick random next edge
+                const nextEdge = availableEdges[Math.floor(Math.random() * availableEdges.length)];
+                this.edge = nextEdge;
+
+                // Determine direction based on which node we're at
+                if (nextEdge.startNode === currentNodeId) {
+                    this.direction = 1;
+                } else if (nextEdge.endNode === currentNodeId) {
+                    this.direction = nextEdge.oneway ? 1 : -1;
+                } else {
+                    this.direction = 1;
+                }
+            }
+        }
+
+        // Simulation state
+        const NUM_AGENTS = 10000;
+        let agents = [];
+        let running = false;
+        let animationId = null;
+        let speedMultiplier = 1;
+        let agentMarkersLayer = L.layerGroup().addTo(map);
+
+        function initAgents() {
+            agentMarkersLayer.clearLayers();
+            agents = [];
+            for (let i = 0; i < NUM_AGENTS; i++) {
+                agents.push(new Agent(i));
+            }
+        }
+
+        function updateTrafficCounts() {
+            edges.forEach(e => trafficCount[e.id] = 0);
+            agents.forEach(agent => {
+                trafficCount[agent.edge.id]++;
+            });
+        }
+
+        function getTrafficColor(edgeId) {
+            const edge = edgeById[edgeId];
+            const density = trafficCount[edgeId] / edge.capacity;
+
+            if (density < 0.3) return '#00ff00';
+            if (density < 0.6) return '#ffff00';
+            if (density < 0.85) return '#ff8800';
+            return '#ff0000';
+        }
+
+        function updateRoadColors() {
+            edges.forEach(edge => {
+                if (roadPolylines[edge.id]) {
+                    roadPolylines[edge.id].setStyle({ color: getTrafficColor(edge.id) });
+                }
+            });
+        }
+
+        function updateAgentMarkers() {
+            agentMarkersLayer.clearLayers();
+
+            // Show subset of agents for performance
+            const showEvery = Math.max(1, Math.floor(agents.length / 200));
+            agents.forEach((agent, i) => {
+                if (i % showEvery === 0) {
+                    const pos = agent.getPosition();
+                    L.circleMarker(pos, {
+                        radius: 3,
+                        fillColor: '#0066ff',
+                        fillOpacity: 0.9,
+                        stroke: false
+                    }).addTo(agentMarkersLayer);
+                }
+            });
+        }
+
+        function simulate() {
+            if (!running) return;
+
+            agents.forEach(agent => agent.update(speedMultiplier));
+            updateTrafficCounts();
+            updateRoadColors();
+            updateAgentMarkers();
+
+            animationId = requestAnimationFrame(simulate);
+        }
+
+        // Controls
+        const startBtn = document.getElementById('startBtn');
+        const resetBtn = document.getElementById('resetBtn');
+        const speedSlider = document.getElementById('speedSlider');
+        const speedDisplay = document.getElementById('speed');
+
+        startBtn.addEventListener('click', () => {
+            if (running) {
+                running = false;
+                startBtn.textContent = 'Start';
+                if (animationId) cancelAnimationFrame(animationId);
+            } else {
+                running = true;
+                startBtn.textContent = 'Pause';
+                simulate();
+            }
+        });
+
+        resetBtn.addEventListener('click', () => {
+            running = false;
+            startBtn.textContent = 'Start';
+            if (animationId) cancelAnimationFrame(animationId);
+            initAgents();
+            updateTrafficCounts();
+            updateRoadColors();
+            updateAgentMarkers();
+        });
+
+        speedSlider.addEventListener('input', (e) => {
+            speedMultiplier = parseInt(e.target.value);
+            speedDisplay.textContent = speedMultiplier + 'x';
+        });
+
+        // Initialize application
+        async function init() {
+            try {
+                const osmData = await fetchRoadNetwork();
+
+                document.getElementById('loadingStatus').textContent = 'Building road graph...';
+                parseOSMData(osmData);
+
+                document.getElementById('loadingStatus').textContent = 'Drawing roads...';
+                drawRoads();
+
+                document.getElementById('loadingStatus').textContent = 'Initializing agents...';
+                initAgents();
+                updateTrafficCounts();
+                updateRoadColors();
+                updateAgentMarkers();
+
+                // Update UI
+                document.getElementById('roadCount').textContent = edges.length;
+                document.getElementById('nodeCount').textContent = Object.keys(nodes).length;
+
+                // Enable controls
+                startBtn.disabled = false;
+                resetBtn.disabled = false;
+
+                // Hide loading
+                document.getElementById('loading').style.display = 'none';
+
+                console.log('Traffic Simulator initialized with', NUM_AGENTS, 'agents on', edges.length, 'road segments');
+            } catch (error) {
+                console.error('Failed to initialize:', error);
+                document.getElementById('loadingStatus').textContent = 'Failed to load road data. Please refresh the page.';
+            }
+        }
+
+        // Start initialization
+        init();
+    </script>
+</body>
+</html>

make_video.py

@@ -0,0 +1,91 @@
+"""
+Stitch test_images/*.png into test_images/traffic_demo.mp4 (and .gif fallback).
+Uses imageio which is already available via matplotlib's dependency chain.
+"""
+
+import glob
+import os
+import sys
+
+# Ensure imageio[ffmpeg] is available; fall back to gif if not
+try:
+    import imageio.v3 as iio
+    import imageio
+    HAVE_IMAGEIO = True
+except ImportError:
+    HAVE_IMAGEIO = False
+
+if not HAVE_IMAGEIO:
+    print("imageio not found – install with: pip install imageio[ffmpeg]")
+    sys.exit(1)
+
+IMG_DIR = os.path.join(os.path.dirname(__file__), "test_images")
+frames_paths = sorted(glob.glob(os.path.join(IMG_DIR, "img_*.png")))
+
+if not frames_paths:
+    print("No images found in test_images/. Run test_generate_images.py first.")
+    sys.exit(1)
+
+print(f"Found {len(frames_paths)} frames.")
+
+# Load frames: ensure RGB and uniform size (tight layout may vary by 1-2 px)
+from PIL import Image as _PILImage
+import numpy as _np
+
+raw = []
+for p in frames_paths:
+    img = iio.imread(p)
+    if img.ndim == 3 and img.shape[2] == 4:
+        img = img[:, :, :3]
+    raw.append(img)
+
+# Use the most common size as target
+from collections import Counter as _Counter
+size_counts = _Counter((f.shape[1], f.shape[0]) for f in raw)
+target_w, target_h = size_counts.most_common(1)[0][0]
+# Round to even dimensions (required by h264 / hevc chroma subsampling)
+target_w += target_w % 2
+target_h += target_h % 2
+frames = []
+for img in raw:
+    if img.shape[1] != target_w or img.shape[0] != target_h:
+        img = _np.array(_PILImage.fromarray(img).resize((target_w, target_h), _PILImage.LANCZOS))
+    frames.append(img)
+print(f"Frames normalised to {target_w}×{target_h}")
+
+# --- MP4 via imageio / ffmpeg plugin ---
+mp4_path = os.path.join(IMG_DIR, "traffic_demo.mp4")
+try:
+    fps = 10
+    for codec in ("libx264", "h264", "libx265", "mpeg4"):
+        try:
+            iio.imwrite(mp4_path, frames, fps=fps, codec=codec)
+            print(f"  codec: {codec}")
+            break
+        except Exception as ce:
+            last_err = ce
+    else:
+        raise last_err
+    print(f"MP4 saved: {mp4_path}  ({len(frames)} frames @ {fps} fps)")
+except Exception as e:
+    print(f"MP4 failed ({e}), falling back to GIF…")
+    mp4_path = None
+
+# --- GIF (full resolution, works without ffmpeg) ---
+gif_path = os.path.join(IMG_DIR, "traffic_demo.gif")
+try:
+    from PIL import Image
+
+    pil_frames = [Image.fromarray(f) for f in frames]
+    pil_frames[0].save(
+        gif_path,
+        save_all=True,
+        append_images=pil_frames[1:],
+        duration=100,   # ms per frame (~10 fps)
+        loop=0,
+        optimize=False,
+    )
+    w, h = pil_frames[0].size
+    print(f"GIF  saved: {gif_path}  ({len(pil_frames)} frames @ ~10 fps, {w}×{h})")
+except Exception as e:
+    print(f"GIF failed: {e}")

make_video_dijkstra.py

@@ -0,0 +1,84 @@
+"""
+Stitch test_images_dijkstra/*.png into test_images_dijkstra/traffic_demo_dijkstra.mp4 (and .gif fallback).
+"""
+
+import glob
+import os
+import sys
+
+try:
+    import imageio.v3 as iio
+    import imageio
+    HAVE_IMAGEIO = True
+except ImportError:
+    HAVE_IMAGEIO = False
+
+if not HAVE_IMAGEIO:
+    print("imageio not found – install with: pip install imageio[ffmpeg]")
+    sys.exit(1)
+
+IMG_DIR = os.path.join(os.path.dirname(__file__), "test_images_dijkstra")
+frames_paths = sorted(glob.glob(os.path.join(IMG_DIR, "img_*.png")))
+
+if not frames_paths:
+    print("No images found in test_images_dijkstra/. Run test_dijkstra_policy.py first.")
+    sys.exit(1)
+
+print(f"Found {len(frames_paths)} frames.")
+
+from PIL import Image as _PILImage
+import numpy as _np
+from collections import Counter as _Counter
+
+raw = []
+for p in frames_paths:
+    img = iio.imread(p)
+    if img.ndim == 3 and img.shape[2] == 4:
+        img = img[:, :, :3]
+    raw.append(img)
+
+size_counts = _Counter((f.shape[1], f.shape[0]) for f in raw)
+target_w, target_h = size_counts.most_common(1)[0][0]
+target_w += target_w % 2
+target_h += target_h % 2
+frames = []
+for img in raw:
+    if img.shape[1] != target_w or img.shape[0] != target_h:
+        img = _np.array(_PILImage.fromarray(img).resize((target_w, target_h), _PILImage.LANCZOS))
+    frames.append(img)
+print(f"Frames normalised to {target_w}×{target_h}")
+
+mp4_path = os.path.join(IMG_DIR, "traffic_demo_dijkstra.mp4")
+try:
+    fps = 10
+    for codec in ("libx264", "h264", "libx265", "mpeg4"):
+        try:
+            iio.imwrite(mp4_path, frames, fps=fps, codec=codec)
+            print(f"  codec: {codec}")
+            break
+        except Exception as ce:
+            last_err = ce
+    else:
+        raise last_err
+    print(f"MP4 saved: {mp4_path}  ({len(frames)} frames @ {fps} fps)")
+except Exception as e:
+    print(f"MP4 failed ({e}), falling back to GIF…")
+    mp4_path = None
+
+gif_path = os.path.join(IMG_DIR, "traffic_demo_dijkstra.gif")
+try:
+    from PIL import Image
+
+    pil_frames = [Image.fromarray(f) for f in frames]
+    pil_frames[0].save(
+        gif_path,
+        save_all=True,
+        append_images=pil_frames[1:],
+        duration=100,
+        loop=0,
+        optimize=False,
+    )
+    w, h = pil_frames[0].size
+    print(f"GIF  saved: {gif_path}  ({len(pil_frames)} frames @ ~10 fps, {w}×{h})")
+except Exception as e:
+    print(f"GIF failed: {e}")

models.py

@@ -0,0 +1,73 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Data models for the Road Traffic Simulator Environment.
+
+The agent controls a single car navigating from a start to end point
+in San Francisco, surrounded by background traffic.
+"""
+
+from typing import Optional
+from pydantic import Field
+
+from openenv.core.env_server.types import Action, Observation
+
+
+class RoadTrafficSimulatorAction(Action):
+    """
+    Action for the traffic navigation environment.
+
+    At each intersection, the agent chooses which outgoing road segment to take.
+    The index is into the list of available outgoing edges at the current node,
+    sorted by edge ID for determinism. Invalid indices are clipped to valid range.
+    """
+
+    next_edge_index: int = Field(
+        default=0,
+        description=(
+            "Index (0-based) of the outgoing edge to take at the current intersection. "
+            "Must be in [0, available_actions - 1]. Out-of-range values are clipped."
+        ),
+    )
+
+
+class RoadTrafficSimulatorObservation(Observation):
+    """
+    Observation from the traffic navigation environment.
+
+    Includes the agent car's current GPS position, goal position,
+    distance to goal, number of route choices available, and a
+    bird's-eye-view screenshot of the map showing real-time traffic
+    density (green=free-flow → red=congested).
+    """
+
+    # Agent position
+    lat: float = Field(default=0.0, description="Current latitude of the agent car")
+    lon: float = Field(default=0.0, description="Current longitude of the agent car")
+
+    # Goal
+    goal_lat: float = Field(default=0.0, description="Destination latitude")
+    goal_lon: float = Field(default=0.0, description="Destination longitude")
+    distance_to_goal: float = Field(
+        default=0.0, description="Straight-line distance to goal in meters"
+    )
+
+    # Action space info
+    available_actions: int = Field(
+        default=1,
+        description="Number of valid outgoing edges from current node (action range: [0, available_actions-1])",
+    )
+
+    # Visual observation: 400x400 PNG, base64-encoded
+    map_screenshot: str = Field(
+        default="",
+        description=(
+            "Base64-encoded PNG (400×400 px) showing the road network coloured by "
+            "traffic density. Blue dot = agent, green star = start, red star = goal, "
+            "dashed cyan = planned shortest route."
+        ),
+    )

openenv.yaml

@@ -0,0 +1,7 @@
+spec_version: 1
+name: road_traffic_simulator_env
+type: space
+runtime: fastapi
+app: server.app:app
+port: 8000
+

openenv_road_traffic_simulator_env.egg-info/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: openenv-road_traffic_simulator_env
+Version: 0.1.0
+Summary: Road Traffic Simulator Env environment for OpenEnv
+Requires-Python: >=3.10
+Requires-Dist: openenv-core[core]>=0.2.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: matplotlib>=3.8.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: imageio[pyav]>=2.37.2
+Requires-Dist: pillow>=12.1.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"

openenv_road_traffic_simulator_env.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+README.md
+__init__.py
+client.py
+make_video.py
+models.py
+pyproject.toml
+test_generate_images.py
+./__init__.py
+./client.py
+./make_video.py
+./models.py
+./test_generate_images.py
+openenv_road_traffic_simulator_env.egg-info/PKG-INFO
+openenv_road_traffic_simulator_env.egg-info/SOURCES.txt
+openenv_road_traffic_simulator_env.egg-info/dependency_links.txt
+openenv_road_traffic_simulator_env.egg-info/entry_points.txt
+openenv_road_traffic_simulator_env.egg-info/requires.txt
+openenv_road_traffic_simulator_env.egg-info/top_level.txt
+server/__init__.py
+server/app.py
+server/road_traffic_simulator_env_environment.py

openenv_road_traffic_simulator_env.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

openenv_road_traffic_simulator_env.egg-info/entry_points.txt

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

openenv_road_traffic_simulator_env.egg-info/requires.txt

@@ -0,0 +1,10 @@
+openenv-core[core]>=0.2.0
+requests>=2.31.0
+matplotlib>=3.8.0
+numpy>=1.26.0
+imageio[pyav]>=2.37.2
+pillow>=12.1.1
+
+[dev]
+pytest>=8.0.0
+pytest-cov>=4.0.0

openenv_road_traffic_simulator_env.egg-info/top_level.txt

@@ -0,0 +1 @@
+road_traffic_simulator_env

pyproject.toml

@@ -0,0 +1,43 @@
+# 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-road_traffic_simulator_env"
+version = "0.1.0"
+description = "Road Traffic Simulator 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.0",
+    # Environment-specific dependencies
+    "requests>=2.31.0",
+    "matplotlib>=3.8.0",
+    "numpy>=1.26.0",
+    "imageio[pyav]>=2.37.2",
+    "pillow>=12.1.1",
+]
+
+[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 road_traffic_simulator_env.server.app
+server = "road_traffic_simulator_env.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["road_traffic_simulator_env", "road_traffic_simulator_env.server"]
+package-dir = { "road_traffic_simulator_env" = ".", "road_traffic_simulator_env.server" = "server" }

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.
+
+"""Road Traffic Simulator Env environment server components."""
+
+from .road_traffic_simulator_env_environment import RoadTrafficSimulatorEnvironment
+
+__all__ = ["RoadTrafficSimulatorEnvironment"]

server/app.py

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

server/requirements.txt

@@ -0,0 +1,6 @@
+openenv[core]>=0.2.0
+fastapi>=0.115.0
+uvicorn>=0.24.0
+requests>=2.31.0
+matplotlib>=3.8.0
+numpy>=1.26.0

server/road_traffic_simulator_env_environment.py

@@ -0,0 +1,729 @@
+# 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.
+
+"""
+Road Traffic Simulator – RL Environment.
+
+The agent controls a single car navigating from a random start node to a
+random end node in downtown San Francisco.  2 000 background vehicles create
+realistic traffic that the agent must route around.
+
+Observation
+-----------
+* lat / lon          – current GPS position
+* goal_lat/goal_lon  – destination GPS position
+* distance_to_goal   – straight-line metres to goal
+* available_actions  – number of outgoing edges (action range)
+* map_screenshot     – 400×400 PNG base64, roads coloured by traffic density
+
+Action
+------
+* next_edge_index    – which outgoing edge to follow at the current node
+
+Reward
+------
+  -1.0   per step  (time penalty)
+  -3.0 * edge_density  (congestion penalty for traversed edge, density ∈ [0,1])
+  +progress_reward      (metres gained toward goal × 0.05)
+  +500.0 on reaching goal
+"""
+
+import base64
+import heapq
+import io
+import math
+import random
+from collections import defaultdict
+from uuid import uuid4
+from typing import Dict, List, Optional, Tuple
+
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+from matplotlib.collections import LineCollection
+
+import requests
+
+from openenv.core.env_server.interfaces import Environment
+from openenv.core.env_server.types import State
+
+from models import RoadTrafficSimulatorAction, RoadTrafficSimulatorObservation
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+BBOX = dict(south=37.770, west=-122.430, north=37.800, east=-122.395)
+
+NUM_BG_AGENTS = 5000
+BG_SUBSTEPS_PER_RL_STEP = 60   # background traffic advances this many mini-steps per RL step
+MAX_RL_STEPS = 300              # episode time limit
+GOAL_RADIUS_M = 50.0            # metres – agent "arrives" when within this distance
+
+# Road rendering: draw in ascending z-order so major roads appear on top
+_HW_LAYERS    = ["unclassified", "residential", "tertiary", "secondary", "primary", "trunk", "motorway"]
+_HW_ROAD_LW   = {"motorway": 4.0, "trunk": 3.4, "primary": 2.8, "secondary": 2.2,
+                  "tertiary": 1.6, "residential": 1.1, "unclassified": 0.8}
+_HW_OUTLINE_LW= {"motorway": 6.2, "trunk": 5.4, "primary": 4.6, "secondary": 3.6,
+                  "tertiary": 2.7, "residential": 1.9, "unclassified": 1.4}
+
+# Map tile settings
+_TILE_ZOOM = 16
+_TILE_URLS = [
+    "https://basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png",
+    "https://tile.openstreetmap.org/{z}/{x}/{y}.png",
+]
+_TILE_HEADERS = {"User-Agent": "SFTrafficSimEnv/1.0 (rl-research)"}
+
+# Module-level caches
+_ROAD_NETWORK: Optional[Tuple] = None
+_BASEMAP: Optional[Tuple] = None   # (np.ndarray, [left_lon, right_lon, bottom_lat, top_lat])
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _haversine(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
+    """Return distance in metres between two GPS points."""
+    R = 6_371_000.0
+    dlat = math.radians(lat2 - lat1)
+    dlon = math.radians(lon2 - lon1)
+    a = math.sin(dlat / 2) ** 2 + (
+        math.cos(math.radians(lat1))
+        * math.cos(math.radians(lat2))
+        * math.sin(dlon / 2) ** 2
+    )
+    return R * 2 * math.atan2(math.sqrt(a), math.sqrt(1 - a))
+
+
+def _traffic_color(density: float) -> tuple:
+    """Return RGBA tuple with alpha tied to congestion: free-flow nearly transparent."""
+    if density < 0.20:
+        return (0.00, 0.80, 0.27, 0.22)   # green  – barely visible, let map show
+    if density < 0.50:
+        return (1.00, 0.87, 0.00, 0.60)   # yellow – semi-transparent
+    if density < 0.80:
+        return (1.00, 0.53, 0.00, 0.80)   # orange
+    return (1.00, 0.13, 0.00, 0.95)       # red jam – nearly opaque
+
+
+def _capacity(highway: str, lanes: int) -> int:
+    base = {"motorway": 50, "trunk": 40, "primary": 30, "secondary": 25,
+            "tertiary": 20, "residential": 15}.get(highway, 10)
+    return max(5, round(base * lanes / 2))
+
+
+# ---------------------------------------------------------------------------
+# Map tile helpers  (basemap cached at module level)
+# ---------------------------------------------------------------------------
+
+def _tile_coords(lat: float, lon: float, zoom: int) -> Tuple[int, int]:
+    n = 2 ** zoom
+    x = int((lon + 180.0) / 360.0 * n)
+    lat_r = math.radians(lat)
+    y = int((1.0 - math.asinh(math.tan(lat_r)) / math.pi) / 2.0 * n)
+    return x, y
+
+
+def _tile_nw(tx: int, ty: int, zoom: int) -> Tuple[float, float]:
+    """Return (lat, lon) of the NW corner of tile (tx, ty)."""
+    n = 2 ** zoom
+    lon = tx / n * 360.0 - 180.0
+    lat = math.degrees(math.atan(math.sinh(math.pi * (1.0 - 2.0 * ty / n))))
+    return lat, lon
+
+
+def _fetch_basemap() -> Tuple:
+    from PIL import Image as PILImage
+    import numpy as np
+
+    zoom = _TILE_ZOOM
+    tx_min, ty_min = _tile_coords(BBOX["north"], BBOX["west"], zoom)
+    tx_max, ty_max = _tile_coords(BBOX["south"], BBOX["east"], zoom)
+
+    cols = tx_max - tx_min + 1
+    rows = ty_max - ty_min + 1
+    canvas = PILImage.new("RGB", (cols * 256, rows * 256), (17, 17, 27))
+
+    for tx in range(tx_min, tx_max + 1):
+        for ty in range(ty_min, ty_max + 1):
+            for url_tmpl in _TILE_URLS:
+                url = url_tmpl.format(z=zoom, x=tx, y=ty)
+                try:
+                    r = requests.get(url, headers=_TILE_HEADERS, timeout=15)
+                    r.raise_for_status()
+                    tile = PILImage.open(io.BytesIO(r.content)).convert("RGB")
+                    canvas.paste(tile, ((tx - tx_min) * 256, (ty - ty_min) * 256))
+                    break
+                except Exception:
+                    continue
+
+    img_arr = np.array(canvas)
+    nw_lat, nw_lon = _tile_nw(tx_min, ty_min, zoom)
+    se_lat, se_lon = _tile_nw(tx_max + 1, ty_max + 1, zoom)
+    # extent for imshow: [left, right, bottom, top]
+    extent = [nw_lon, se_lon, se_lat, nw_lat]
+    return img_arr, extent
+
+
+def _get_basemap() -> Tuple:
+    global _BASEMAP
+    if _BASEMAP is None:
+        _BASEMAP = _fetch_basemap()
+    return _BASEMAP
+
+
+# ---------------------------------------------------------------------------
+# OSM fetch + parse  (cached at module level so only fetched once)
+# ---------------------------------------------------------------------------
+
+
+def _fetch_road_network() -> Tuple[Dict, List[Dict], Dict]:
+    query = (
+        "[out:json][timeout:60];\n"
+        "(\n"
+        '  way["highway"~"^(motorway|trunk|primary|secondary|tertiary|residential|unclassified)$"]\n'
+        f"      ({BBOX['south']},{BBOX['west']},{BBOX['north']},{BBOX['east']});\n"
+        ");\n"
+        "out body;\n"
+        ">;\n"
+        "out skel qt;\n"
+    )
+    servers = [
+        "https://overpass-api.de/api/interpreter",
+        "https://overpass.kumi.systems/api/interpreter",
+    ]
+    data = None
+    for url in servers:
+        try:
+            r = requests.post(
+                url,
+                data={"data": query},
+                timeout=90,
+            )
+            r.raise_for_status()
+            data = r.json()
+            break
+        except Exception:
+            continue
+    if data is None:
+        raise RuntimeError("Failed to fetch OSM data from all Overpass servers.")
+
+    return _parse_osm(data)
+
+
+def _parse_osm(osm_data: Dict) -> Tuple[Dict, List[Dict], Dict]:
+    node_coords: Dict[int, Tuple[float, float]] = {}
+    for el in osm_data["elements"]:
+        if el["type"] == "node":
+            node_coords[el["id"]] = (el["lat"], el["lon"])
+
+    nodes: Dict = {}
+    edges: List[Dict] = []
+    edge_by_id: Dict[str, Dict] = {}
+    edge_id_counter = 0
+
+    for el in osm_data["elements"]:
+        if el["type"] != "way" or not el.get("nodes") or len(el["nodes"]) < 2:
+            continue
+        tags = el.get("tags", {})
+        highway = tags.get("highway", "unclassified")
+        oneway = tags.get("oneway") == "yes"
+        lanes = int(tags.get("lanes", 2))
+        cap = _capacity(highway, lanes)
+
+        for i in range(len(el["nodes"]) - 1):
+            s_id, e_id = el["nodes"][i], el["nodes"][i + 1]
+            if s_id not in node_coords or e_id not in node_coords:
+                continue
+            slat, slon = node_coords[s_id]
+            elat, elon = node_coords[e_id]
+            length = _haversine(slat, slon, elat, elon)
+
+            eid = f"e{edge_id_counter}"
+            edge_id_counter += 1
+            edge = {
+                "id": eid,
+                "start_node": s_id,
+                "end_node": e_id,
+                "coords": [(slat, slon), (elat, elon)],
+                "length": length,
+                "capacity": cap,
+                "highway": highway,
+                "oneway": oneway,
+            }
+            edges.append(edge)
+            edge_by_id[eid] = edge
+
+            for nid, lat, lon in [(s_id, slat, slon), (e_id, elat, elon)]:
+                if nid not in nodes:
+                    nodes[nid] = {"id": nid, "lat": lat, "lon": lon,
+                                  "out_edges": [], "in_edges": []}
+
+            nodes[s_id]["out_edges"].append(eid)
+            nodes[e_id]["in_edges"].append(eid)
+            if not oneway:
+                nodes[e_id]["out_edges"].append(eid)
+                nodes[s_id]["in_edges"].append(eid)
+
+    return nodes, edges, edge_by_id
+
+
+def _get_road_network() -> Tuple[Dict, List[Dict], Dict]:
+    global _ROAD_NETWORK
+    if _ROAD_NETWORK is None:
+        _ROAD_NETWORK = _fetch_road_network()
+    return _ROAD_NETWORK
+
+
+# ---------------------------------------------------------------------------
+# Background agent
+# ---------------------------------------------------------------------------
+
+class _BgAgent:
+    __slots__ = ("edge", "progress", "direction", "speed")
+
+    def __init__(self, edges: List[Dict]):
+        self.edge = random.choice(edges)
+        self.progress: float = random.random()
+        self.direction: int = 1 if self.edge["oneway"] else random.choice([1, -1])
+        self.speed: float = 0.012 + random.random() * 0.018
+
+    def _current_node_id(self):
+        if self.direction == 1:
+            return self.edge["end_node"]
+        return self.edge["start_node"]
+
+    def step(
+        self,
+        traffic_count: Dict[str, int],
+        nodes: Dict,
+        edges: List[Dict],
+        edge_by_id: Dict[str, Dict],
+    ):
+        density = traffic_count.get(self.edge["id"], 0) / self.edge["capacity"]
+        # Near-standstill in heavy jams (density 1.0 → speed_factor 0.02)
+        speed_factor = max(0.02, 1.0 - density ** 0.7 * 0.98)
+        length_factor = 50.0 / max(20.0, self.edge["length"])
+        self.progress += self.speed * speed_factor * length_factor
+
+        if self.progress >= 1.0:
+            self.progress = 0.0
+            nid = self._current_node_id()
+            node = nodes.get(nid)
+            if not node:
+                self.edge = random.choice(edges)
+                self.direction = 1 if self.edge["oneway"] else random.choice([1, -1])
+                return
+
+            choices = [
+                e for eid in node["out_edges"]
+                if (e := edge_by_id.get(eid)) and e["id"] != self.edge["id"]
+            ]
+            if not choices:
+                if not self.edge["oneway"]:
+                    self.direction *= -1
+                else:
+                    self.edge = random.choice(edges)
+                    self.direction = 1
+                return
+
+            next_edge = random.choice(choices)
+            self.edge = next_edge
+            if next_edge["start_node"] == nid:
+                self.direction = 1
+            elif not next_edge["oneway"]:
+                self.direction = -1
+            else:
+                self.direction = 1
+
+    def get_position(self) -> Tuple[float, float]:
+        p = self.progress if self.direction == 1 else 1.0 - self.progress
+        (slat, slon), (elat, elon) = self.edge["coords"]
+        return (slat + (elat - slat) * p, slon + (elon - slon) * p)
+
+
+# ---------------------------------------------------------------------------
+# Dijkstra shortest path
+# ---------------------------------------------------------------------------
+
+def _dijkstra(
+    nodes: Dict, edge_by_id: Dict[str, Dict], start_id: int, end_id: int
+) -> Tuple[List[str], float]:
+    dist: Dict[int, float] = {start_id: 0.0}
+    prev: Dict[int, Optional[Tuple[int, str]]] = {start_id: None}
+    pq = [(0.0, start_id)]
+
+    while pq:
+        d, u = heapq.heappop(pq)
+        if d > dist.get(u, math.inf):
+            continue
+        if u == end_id:
+            break
+        node = nodes.get(u)
+        if not node:
+            continue
+        for eid in node["out_edges"]:
+            edge = edge_by_id.get(eid)
+            if not edge:
+                continue
+            # Determine the neighbour node
+            if edge["start_node"] == u:
+                v = edge["end_node"]
+            elif not edge["oneway"]:
+                v = edge["start_node"]
+            else:
+                continue
+            nd = d + edge["length"]
+            if nd < dist.get(v, math.inf):
+                dist[v] = nd
+                prev[v] = (u, eid)
+                heapq.heappush(pq, (nd, v))
+
+    # Reconstruct edge path
+    path: List[str] = []
+    cur = end_id
+    while cur in prev and prev[cur] is not None:
+        parent, eid = prev[cur]
+        path.append(eid)
+        cur = parent
+    path.reverse()
+    return path, dist.get(end_id, math.inf)
+
+
+# ---------------------------------------------------------------------------
+# Outgoing edges from a node (respecting one-way)
+# ---------------------------------------------------------------------------
+
+def _outgoing_edges(
+    node_id: int,
+    nodes: Dict,
+    edge_by_id: Dict,
+    prev_node_id: Optional[int] = None,
+) -> List[Dict]:
+    """Return outgoing edges from node_id, excluding U-turns back to prev_node_id.
+
+    If excluding the U-turn would leave no options, all edges are returned
+    (so the agent can always move).
+    """
+    node = nodes.get(node_id)
+    if not node:
+        return []
+    result = []
+    for eid in node["out_edges"]:
+        e = edge_by_id.get(eid)
+        if not e:
+            continue
+        # For oneway edges, must originate at start_node
+        if e["oneway"] and e["start_node"] != node_id:
+            continue
+        result.append(e)
+    result = sorted(result, key=lambda e: e["id"])   # deterministic order
+
+    # Remove U-turn (edge that leads straight back to where we came from)
+    if prev_node_id is not None and len(result) > 1:
+        def _neighbour(e: Dict) -> int:
+            return e["end_node"] if e["start_node"] == node_id else e["start_node"]
+        filtered = [e for e in result if _neighbour(e) != prev_node_id]
+        if filtered:
+            return filtered
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Environment
+# ---------------------------------------------------------------------------
+
+class RoadTrafficSimulatorEnvironment(Environment):
+    """
+    Single-car navigation environment in downtown San Francisco.
+
+    The agent selects which road segment to follow at each intersection.
+    Background traffic creates dynamic congestion that the agent should avoid.
+    """
+
+    SUPPORTS_CONCURRENT_SESSIONS: bool = True
+
+    def __init__(self):
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+
+        self.nodes, self.edges, self.edge_by_id = _get_road_network()
+
+        # Nodes with ≥2 outgoing edges so the agent always has a real choice
+        self._viable_nodes = [
+            nid for nid, n in self.nodes.items()
+            if len(_outgoing_edges(nid, self.nodes, self.edge_by_id)) >= 2
+        ]
+
+        self.traffic_count: Dict[str, int] = {e["id"]: 0 for e in self.edges}
+        self.bg_agents: List[_BgAgent] = []
+
+        # Agent car state
+        self.agent_node_id: Optional[int] = None
+        self.prev_node_id: Optional[int] = None   # for U-turn prevention
+        self.start_node_id: Optional[int] = None
+        self.end_node_id: Optional[int] = None
+        self.planned_route: List[str] = []    # edge ids of shortest path
+        self.prev_dist_to_goal: float = 0.0
+
+    # ------------------------------------------------------------------
+    # OpenEnv interface
+    # ------------------------------------------------------------------
+
+    def reset(self) -> RoadTrafficSimulatorObservation:
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+
+        # Pick start and end nodes that are at least 400 m apart
+        for _ in range(200):
+            s = random.choice(self._viable_nodes)
+            e = random.choice(self._viable_nodes)
+            if s == e:
+                continue
+            sn, en = self.nodes[s], self.nodes[e]
+            if _haversine(sn["lat"], sn["lon"], en["lat"], en["lon"]) >= 400.0:
+                self.start_node_id = s
+                self.end_node_id = e
+                break
+        else:
+            self.start_node_id = self._viable_nodes[0]
+            self.end_node_id = self._viable_nodes[-1]
+
+        self.agent_node_id = self.start_node_id
+        self.prev_node_id = None
+
+        # Pre-compute shortest path
+        self.planned_route, _ = _dijkstra(
+            self.nodes, self.edge_by_id, self.start_node_id, self.end_node_id
+        )
+
+        # Initialise background traffic
+        self.bg_agents = [_BgAgent(self.edges) for _ in range(NUM_BG_AGENTS)]
+        self._update_traffic_counts()
+
+        sn = self.nodes[self.start_node_id]
+        en = self.nodes[self.end_node_id]
+        self.prev_dist_to_goal = _haversine(sn["lat"], sn["lon"], en["lat"], en["lon"])
+
+        return self._make_observation(reward=0.0, done=False)
+
+    def step(self, action: RoadTrafficSimulatorAction) -> RoadTrafficSimulatorObservation:
+        self._state.step_count += 1
+
+        # ---- Agent moves ----
+        out_edges = _outgoing_edges(
+            self.agent_node_id, self.nodes, self.edge_by_id, self.prev_node_id
+        )
+        if not out_edges:
+            # True dead end – episode over
+            return self._make_observation(reward=-50.0, done=True)
+
+        idx = max(0, min(action.next_edge_index, len(out_edges) - 1))
+        chosen_edge = out_edges[idx]
+
+        # Edge density at time of traversal
+        density = self.traffic_count.get(chosen_edge["id"], 0) / chosen_edge["capacity"]
+
+        # Move agent to next node
+        self.prev_node_id = self.agent_node_id
+        if chosen_edge["start_node"] == self.agent_node_id:
+            self.agent_node_id = chosen_edge["end_node"]
+        else:
+            self.agent_node_id = chosen_edge["start_node"]
+
+        # ---- Advance background traffic ----
+        for _ in range(BG_SUBSTEPS_PER_RL_STEP):
+            for ag in self.bg_agents:
+                ag.step(self.traffic_count, self.nodes, self.edges, self.edge_by_id)
+            self._update_traffic_counts()
+
+        # ---- Reward ----
+        an = self.nodes[self.agent_node_id]
+        en = self.nodes[self.end_node_id]
+        dist_to_goal = _haversine(an["lat"], an["lon"], en["lat"], en["lon"])
+
+        # Time cost scales with congestion: congested edge takes up to 5× longer
+        time_penalty = -(1.0 + density * 4.0)
+        traffic_penalty = 0.0   # absorbed into time_penalty
+        progress_reward = (self.prev_dist_to_goal - dist_to_goal) * 0.05
+        self.prev_dist_to_goal = dist_to_goal
+
+        reward = time_penalty + traffic_penalty + progress_reward
+
+        # ---- Termination ----
+        done = False
+        if dist_to_goal <= GOAL_RADIUS_M:
+            reward += 500.0
+            done = True
+        elif self._state.step_count >= MAX_RL_STEPS:
+            done = True
+
+        return self._make_observation(reward=reward, done=done)
+
+    @property
+    def state(self) -> State:
+        return self._state
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _update_traffic_counts(self):
+        for eid in self.traffic_count:
+            self.traffic_count[eid] = 0
+        for ag in self.bg_agents:
+            eid = ag.edge["id"]
+            self.traffic_count[eid] = self.traffic_count.get(eid, 0) + 1
+
+    def _make_observation(self, reward: float, done: bool) -> RoadTrafficSimulatorObservation:
+        an = self.nodes[self.agent_node_id]
+        en = self.nodes[self.end_node_id]
+        dist = _haversine(an["lat"], an["lon"], en["lat"], en["lon"])
+        out_edges = _outgoing_edges(
+            self.agent_node_id, self.nodes, self.edge_by_id, self.prev_node_id
+        )
+        screenshot = self._render()
+
+        return RoadTrafficSimulatorObservation(
+            lat=an["lat"],
+            lon=an["lon"],
+            goal_lat=en["lat"],
+            goal_lon=en["lon"],
+            distance_to_goal=dist,
+            available_actions=max(1, len(out_edges)),
+            map_screenshot=screenshot,
+            done=done,
+            reward=reward,
+            metadata={
+                "step": self._state.step_count,
+                "episode_id": self._state.episode_id,
+                "start_node": self.start_node_id,
+                "end_node": self.end_node_id,
+            },
+        )
+
+    def _render(self) -> str:
+        """Render 512×512 traffic map and return as base64 PNG string."""
+        BG = "#0d1117"
+        BORDER = "#111827"
+
+        fig, ax = plt.subplots(figsize=(5.12, 5.12), dpi=200)
+        fig.patch.set_facecolor(BG)
+        ax.set_facecolor(BG)
+        ax.set_xlim(BBOX["west"], BBOX["east"])
+        ax.set_ylim(BBOX["south"], BBOX["north"])
+        ax.set_aspect("auto")
+        ax.axis("off")
+
+        # --- Real SF map tiles as background ---
+        bm_img, bm_extent = _get_basemap()
+        ax.imshow(bm_img, extent=bm_extent, aspect="auto",
+                  zorder=0, interpolation="bilinear", alpha=1.0)
+
+        # --- Group edges by highway type, compute traffic colour per segment ---
+        by_hw: Dict[str, Dict] = {hw: {"segs": [], "colors": []} for hw in _HW_LAYERS}
+        for edge in self.edges:
+            hw = edge["highway"] if edge["highway"] in _HW_LAYERS else "unclassified"
+            density = self.traffic_count.get(edge["id"], 0) / edge["capacity"]
+            (slat, slon), (elat, elon) = edge["coords"]
+            by_hw[hw]["segs"].append([(slon, slat), (elon, elat)])
+            by_hw[hw]["colors"].append(_traffic_color(density))
+
+        # Single-pass draw with RGBA colors (alpha encodes congestion level).
+        # No dark outline pass – we want the basemap to show through clearly.
+        for z, hw in enumerate(_HW_LAYERS):
+            data = by_hw[hw]
+            if not data["segs"]:
+                continue
+            rlw = _HW_ROAD_LW.get(hw, 0.8)
+            ax.add_collection(LineCollection(
+                data["segs"], colors=data["colors"], linewidths=rlw, zorder=z + 1))
+
+        # --- Planned route (bright cyan dashed, on top of roads) ---
+        if self.planned_route:
+            route_segs = []
+            for eid in self.planned_route:
+                e = self.edge_by_id.get(eid)
+                if e:
+                    (slat, slon), (elat, elon) = e["coords"]
+                    route_segs.append([(slon, slat), (elon, elat)])
+            if route_segs:
+                zr = len(_HW_LAYERS) + 2
+                ax.add_collection(LineCollection(
+                    route_segs, colors="#00ccff", linewidths=2.5,
+                    linestyles="dashed", alpha=0.95, zorder=zr))
+
+        zm = len(_HW_LAYERS) + 4   # marker z-base
+
+        # --- Start marker ---
+        sn = self.nodes[self.start_node_id]
+        ax.plot(sn["lon"], sn["lat"], marker="*", color="#00dd66",
+                markersize=16, zorder=zm, markeredgecolor="white", markeredgewidth=0.8)
+        ax.text(sn["lon"], sn["lat"] + 0.00035, "START", color="white",
+                fontsize=5.5, ha="center", va="bottom", zorder=zm + 1,
+                bbox=dict(boxstyle="round,pad=0.25", fc="#00884a", ec="none", alpha=0.85))
+
+        # --- Goal marker ---
+        en = self.nodes[self.end_node_id]
+        ax.plot(en["lon"], en["lat"], marker="*", color="#ff3311",
+                markersize=16, zorder=zm, markeredgecolor="white", markeredgewidth=0.8)
+        ax.text(en["lon"], en["lat"] + 0.00035, "GOAL", color="white",
+                fontsize=5.5, ha="center", va="bottom", zorder=zm + 1,
+                bbox=dict(boxstyle="round,pad=0.25", fc="#cc2200", ec="none", alpha=0.85))
+
+        # --- Agent car with direction arrow ---
+        an = self.nodes[self.agent_node_id]
+        ax.plot(an["lon"], an["lat"], marker="o", color="#3388ff",
+                markersize=9, zorder=zm + 2,
+                markeredgecolor="white", markeredgewidth=1.5)
+        if self.prev_node_id and self.prev_node_id in self.nodes:
+            pn = self.nodes[self.prev_node_id]
+            dx = an["lon"] - pn["lon"]
+            dy = an["lat"] - pn["lat"]
+            length = math.hypot(dx, dy)
+            if length > 1e-9:
+                # Arrow tail starts 60 % of the way back from the agent
+                tail_lon = an["lon"] - dx * 0.6
+                tail_lat = an["lat"] - dy * 0.6
+                ax.annotate(
+                    "", xy=(an["lon"], an["lat"]),
+                    xytext=(tail_lon, tail_lat),
+                    arrowprops=dict(
+                        arrowstyle="-|>", color="white", lw=1.2,
+                        mutation_scale=12),
+                    zorder=zm + 3)
+
+        # --- HUD: step count + distance ---
+        dist = _haversine(an["lat"], an["lon"], en["lat"], en["lon"])
+        hud_style = dict(boxstyle="round,pad=0.3", fc=BG, ec="#334455", alpha=0.88)
+        ax.text(0.01, 0.99, f"Step {self._state.step_count}",
+                transform=ax.transAxes, color="#aaaacc", fontsize=6.5,
+                va="top", ha="left", zorder=zm + 5, bbox=hud_style)
+        ax.text(0.99, 0.99, f"Dist  {dist:.0f} m",
+                transform=ax.transAxes, color="#ffdd88", fontsize=6.5,
+                va="top", ha="right", zorder=zm + 5, bbox=hud_style)
+
+        # --- Legend ---
+        from matplotlib.patches import Patch
+        legend_els = [
+            Patch(fc="#00cc44", ec="none", label="Free flow"),
+            Patch(fc="#ffdd00", ec="none", label="Moderate"),
+            Patch(fc="#ff8800", ec="none", label="Heavy"),
+            Patch(fc="#ff2200", ec="none", label="Jam"),
+        ]
+        ax.legend(handles=legend_els, loc="lower left", fontsize=5.5,
+                  facecolor="#131b26", edgecolor="#334455", labelcolor="#cccccc",
+                  framealpha=0.88, ncol=2, handlelength=1.2,
+                  borderpad=0.5, handletextpad=0.4, columnspacing=0.8)
+
+        buf = io.BytesIO()
+        plt.savefig(buf, format="png", dpi=200,
+                    bbox_inches="tight", pad_inches=0.02, facecolor=BG)
+        plt.close(fig)
+        buf.seek(0)
+        return base64.b64encode(buf.read()).decode("utf-8")

test_dijkstra_policy.py

@@ -0,0 +1,133 @@
+"""
+Test the Dijkstra (shortest-path) policy.
+
+At each intersection the policy picks the outgoing edge that matches the
+next edge in the pre-computed shortest route (env.planned_route).
+If the agent drifts off-route (dead-end escape, etc.) it falls back to
+the edge that gets geometrically closest to the goal.
+
+Results are saved to test_images_dijkstra/.
+"""
+
+import base64
+import math
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "server"))
+sys.path.insert(0, os.path.dirname(__file__))
+
+from server.road_traffic_simulator_env_environment import (
+    RoadTrafficSimulatorEnvironment,
+    _outgoing_edges,
+    _haversine,
+)
+from models import RoadTrafficSimulatorAction
+
+OUT_DIR = os.path.join(os.path.dirname(__file__), "test_images_dijkstra")
+os.makedirs(OUT_DIR, exist_ok=True)
+
+TARGET = 100
+
+
+def save_png(b64: str, path: str):
+    with open(path, "wb") as f:
+        f.write(base64.b64decode(b64))
+
+
+class DijkstraPolicy:
+    """Follow env.planned_route; fall back to closest-to-goal edge if off-route."""
+
+    def __init__(self):
+        self._route_idx = 0
+
+    def reset(self):
+        self._route_idx = 0
+
+    def act(self, env: RoadTrafficSimulatorEnvironment) -> int:
+        out_edges = _outgoing_edges(
+            env.agent_node_id, env.nodes, env.edge_by_id, env.prev_node_id
+        )
+        if not out_edges:
+            return 0
+
+        # Try to find the next planned-route edge among the outgoing options
+        while self._route_idx < len(env.planned_route):
+            target_eid = env.planned_route[self._route_idx]
+            for i, e in enumerate(out_edges):
+                if e["id"] == target_eid:
+                    self._route_idx += 1
+                    return i
+            # Planned edge not reachable from here — advance route pointer and retry
+            self._route_idx += 1
+
+        # Off-route or past end: pick the edge whose far end is closest to goal
+        goal = env.nodes[env.end_node_id]
+        best_i, best_d = 0, math.inf
+        for i, e in enumerate(out_edges):
+            nid = e["end_node"] if e["start_node"] == env.agent_node_id else e["start_node"]
+            n = env.nodes.get(nid)
+            if n:
+                d = _haversine(n["lat"], n["lon"], goal["lat"], goal["lon"])
+                if d < best_d:
+                    best_d, best_i = d, i
+        return best_i
+
+
+# ---------------------------------------------------------------------------
+
+print("Initialising environment (OSM data cached from previous run if available)…")
+env = RoadTrafficSimulatorEnvironment()
+policy = DijkstraPolicy()
+
+img_idx = 0
+episode = 0
+total_reward = 0.0
+episodes_done = 0
+
+while img_idx < TARGET:
+    episode += 1
+    obs = env.reset()
+    policy.reset()
+    ep_reward = 0.0
+
+    fname = os.path.join(OUT_DIR, f"img_{img_idx:03d}_ep{episode}_step0.png")
+    save_png(obs.map_screenshot, fname)
+    print(f"[{img_idx+1:3d}/{TARGET}] ep={episode} step=0  "
+          f"start=({obs.lat:.4f},{obs.lon:.4f})  "
+          f"goal=({obs.goal_lat:.4f},{obs.goal_lon:.4f})  "
+          f"dist={obs.distance_to_goal:.0f}m  route_len={len(env.planned_route)} edges"
+          f"  → {os.path.basename(fname)}")
+    img_idx += 1
+    if img_idx >= TARGET:
+        break
+
+    step = 0
+    done = False
+    while not done and img_idx < TARGET:
+        step += 1
+        action_idx = policy.act(env)
+        obs = env.step(RoadTrafficSimulatorAction(next_edge_index=action_idx))
+        done = obs.done
+        ep_reward += obs.reward
+
+        fname = os.path.join(OUT_DIR, f"img_{img_idx:03d}_ep{episode}_step{step}.png")
+        save_png(obs.map_screenshot, fname)
+        print(f"[{img_idx+1:3d}/{TARGET}] ep={episode} step={step}  "
+              f"pos=({obs.lat:.4f},{obs.lon:.4f})  "
+              f"dist={obs.distance_to_goal:.0f}m  "
+              f"reward={obs.reward:+.2f}  "
+              f"done={done}  → {os.path.basename(fname)}")
+        img_idx += 1
+
+    if done:
+        episodes_done += 1
+        total_reward += ep_reward
+        goal_reached = obs.distance_to_goal <= 50.0
+        print(f"  ↳ Episode {episode} finished: steps={step}  "
+              f"total_reward={ep_reward:.1f}  "
+              f"goal={'REACHED ✓' if goal_reached else 'timeout/deadend'}")
+
+print(f"\nDone. {img_idx} images saved to: {OUT_DIR}")
+print(f"Episodes completed: {episodes_done}  avg reward: "
+      f"{total_reward/max(1,episodes_done):.1f}")

test_generate_images.py

@@ -0,0 +1,63 @@
+"""
+Generate 100 screenshots from the traffic environment and save to test_images/.
+Runs multiple episodes; each reset picks a new random start/end.
+"""
+
+import base64
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "server"))
+sys.path.insert(0, os.path.dirname(__file__))
+
+from server.road_traffic_simulator_env_environment import RoadTrafficSimulatorEnvironment
+from models import RoadTrafficSimulatorAction
+
+OUT_DIR = os.path.join(os.path.dirname(__file__), "test_images")
+os.makedirs(OUT_DIR, exist_ok=True)
+
+TARGET = 100
+
+def save_png(b64: str, path: str):
+    with open(path, "wb") as f:
+        f.write(base64.b64decode(b64))
+
+print("Initialising environment (fetching OSM data – first time only, ~10-30 s)…")
+env = RoadTrafficSimulatorEnvironment()
+
+img_idx = 0
+episode = 0
+
+while img_idx < TARGET:
+    episode += 1
+    obs = env.reset()
+
+    fname = os.path.join(OUT_DIR, f"img_{img_idx:03d}_ep{episode}_step0.png")
+    save_png(obs.map_screenshot, fname)
+    print(f"[{img_idx+1:3d}/{TARGET}] ep={episode} step=0  "
+          f"start=({obs.lat:.4f},{obs.lon:.4f})  "
+          f"goal=({obs.goal_lat:.4f},{obs.goal_lon:.4f})  "
+          f"dist={obs.distance_to_goal:.0f}m  → {os.path.basename(fname)}")
+    img_idx += 1
+    if img_idx >= TARGET:
+        break
+
+    step = 0
+    done = False
+    while not done and img_idx < TARGET:
+        step += 1
+        # Cycle through edge choices to get varied paths
+        action_idx = (step - 1) % max(1, obs.available_actions)
+        obs = env.step(RoadTrafficSimulatorAction(next_edge_index=action_idx))
+        done = obs.done
+
+        fname = os.path.join(OUT_DIR, f"img_{img_idx:03d}_ep{episode}_step{step}.png")
+        save_png(obs.map_screenshot, fname)
+        print(f"[{img_idx+1:3d}/{TARGET}] ep={episode} step={step}  "
+              f"pos=({obs.lat:.4f},{obs.lon:.4f})  "
+              f"dist={obs.distance_to_goal:.0f}m  "
+              f"reward={obs.reward:+.2f}  "
+              f"done={done}  → {os.path.basename(fname)}")
+        img_idx += 1
+
+print(f"\nDone. {img_idx} images saved to: {OUT_DIR}")