Forest-Fire/gridworld-openenv

1---2title: Gridworld Openenv3emoji: 🐠4colorFrom: green5colorTo: purple6sdk: docker7pinned: false8license: mit9short_description: RL GridWorld environment API (OpenEnv ready)10---11 12# 🚀 Autonomous Navigation RL Environment (OpenEnv Compatible)13 14A lightweight, API-driven Reinforcement Learning environment that simulates robot navigation in a 2D GridWorld with obstacles, traps, and dynamic challenges.15 16---17 18## 🧠 Overview19 20This project implements a GridWorld environment where an agent must navigate from a start position to a goal while avoiding hazards and penalties.21 22### Environment Elements23 24- 🟫 **Obstacles** — Block movement  25- ⚠️ **Traps** — Penalize the agent  26- 👾 **Enemy (Hard Mode)** — Introduces dynamic difficulty  27 28The environment is exposed via a **FastAPI interface** and is fully **Dockerized** for easy deployment.29 30---31 32## 🎯 Features33 34- ✅ OpenEnv-compliant API  35- ✅ Three difficulty levels: **easy, medium, hard**  36- ✅ Reward normalization (`0.0 → 1.0`)  37- ✅ Fully Dockerized setup  38- ✅ Lightweight and CPU-friendly  39- ✅ Inference script for evaluation  40- ✅ Stable API with no validation errors  41 42---43 44## 🎮 Action Space45 46| Action | Meaning |47|--------|--------|48| `0` | Up |49| `1` | Down |50| `2` | Left |51| `3` | Right |52 53---54 55## 🧮 Reward System56 57The reward function is designed to guide efficient navigation:58 59- ➖ Step penalty (encourages shorter paths)  60- 📏 Distance-based reward shaping  61- ⚠️ Trap penalty  62- 👾 Enemy penalty (hard mode)  63- 🏁 Goal reward  64 65👉 Final reward is **normalized to `[0, 1]`**66 67---68 69## 🌐 API Endpoints70 71### 🔹 Reset Environment72 73```74 75POST /reset?task=easy76 77```78 79**Query Params:**80- `task`: `easy | medium | hard`81 82---83 84### 🔹 Take a Step85 86```87 88POST /step89 90````91 92**Request Body:**93```json94{95  "action": 196}97````98 99**Response:**100 101```json102{103  "state": [x, y],104  "reward": 0.85,105  "done": false106}107```108 109---110 111### 🔹 Get Current State112 113```114GET /state115```116 117---118 119## 🧪 Inference120 121Run the evaluation script:122 123```bash124python inference.py125```126 127### Output Format128 129```130[START]131[STEP] action=...132[STEP] action=...133[END]134```135 136---137 138## 🐳 Docker Setup139 140### Build Image141 142```bash143docker build -t env-test .144```145 146### Run Container147 148```bash149docker run -p 7860:7860 env-test150```151 152The API will be available at:153 154```155http://localhost:7860156```157 158---159 160## 📁 Project Structure161 162```163app/164  ├── api.py        # FastAPI routes165  ├── env.py        # Core environment logic166  ├── models.py     # Data models (request/response)167  ├── tasks.py      # Task configurations168  ├── graders.py    # Evaluation logic169 170inference.py        # Agent interaction script171Dockerfile          # Container configuration172requirements.txt    # Dependencies173openenv.yaml        # OpenEnv specification174LICENSE175```176 177---178 179## 📊 Tasks180 181| Difficulty | Description           |182| ---------- | --------------------- |183| 🟢 Easy    | Fewer obstacles       |184| 🟡 Medium  | More traps            |185| 🔴 Hard    | Enemy + dense hazards |186 187---188 189## ⚙️ State Representation190 191* Format: `[x, y]`192* Represents agent position in the grid193* Fully compliant with OpenEnv expectations194 195---196 197## ✅ Submission Ready198 199* ✔ Correct state format200* ✔ Normalized rewards201* ✔ Stable API responses202* ✔ No validation errors203 204🎉 This environment is **fully evaluator-ready**.205 206---207 208## 📜 License209 210This project is released under the MIT License.211 212Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference