README.md

metadata

title: Cat Rescue
emoji: 🐱
colorFrom: blue
colorTo: green
sdk: docker
pinned: false

🐱 Cat Rescue — OpenEnv Environment

A grid-based reinforcement learning environment where an AI agent navigates rooms to rescue trapped cats.

🎮 Live Demo: https://vizxal-cat-rescue.hf.space

🤗 HF Space: https://huggingface.co/spaces/Vizxal/Cat-Rescue/tree/main

---

🎮 Game Concept

The agent starts at the top-left corner of a grid and must reach every cat before the step budget runs out. Static walls block movement on higher levels, and moving obstacles patrol the grid on the hardest level.

Level	Grid	Cats	Obstacles
1	3 × 3	1	None
2	5 × 5	2	Static walls
3	7 × 7	3	Static walls + 2 moving

Actions

Integer	Direction
0	UP
1	DOWN
2	LEFT
3	RIGHT

Rewards

Event	Reward
Every step taken	−0.1
Hit a wall / boundary	−0.3
Rescue a cat	+1.0
All cats rescued (bonus)	+2.0

---

📁 Project Structure

Cat-Rescue/
├── environment.py   # Core game logic — CatRescueEnv
├── rewards.py       # Reward schedule — CatRescueRewards
├── grader.py        # Episode scoring — CatRescueGrader
├── server.py        # FastAPI server (OpenEnv HTTP API)
├── index.html       # Human playable UI
├── Dockerfile       # Container build for HF Spaces
└── requirements.txt # Python dependencies

---

🚀 Running Locally

# Install dependencies
pip install -r requirements.txt

# Start the server
uvicorn server:app --host 0.0.0.0 --port 7860

Open the interactive API docs at http://localhost:7860/docs

---

🐳 Running with Docker

# Build the image
docker build -t cat-rescue .

# Run the container
docker run -p 7860:7860 cat-rescue

---

🌐 API Endpoints

GET /

Serves the human playable UI.

POST /reset

Start a new episode. Re-initialises the environment.

Request body:

{ "level": 1, "max_steps": 200, "seed": 42 }

POST /step

Take one action. Returns the new observation, reward, done flag, and info dict.

Request body:

{ "action": 0 }

Response:

{
  "observation": { "grid": [...], "agent_pos": [0,1], "cats_rescued": 0 },
  "reward": -0.1,
  "done": false,
  "info": { "event": "step", "cats_rescued": 0, "step_count": 1 }
}

GET /state

Read the current grid state without advancing the episode.

POST /grade

Score a completed episode log.

Request body:

{
  "episode_log": [
    { "action": 1, "reward": -0.1, "done": false, "info": {} }
  ]
}

---

🤖 Quickstart Agent Loop

import requests
import random

BASE = "https://vizxal-cat-rescue.hf.space"

# 1. Start a new episode on level 2
obs = requests.post(f"{BASE}/reset", json={"level": 2, "seed": 0}).json()

done = False
episode_log = []

# 2. Run a random agent
while not done:
    action = random.randint(0, 3)
    resp = requests.post(f"{BASE}/step", json={"action": action}).json()
    done = resp["done"]
    episode_log.append({
        "action": action,
        "reward": resp["reward"],
        "done":   resp["done"],
        "info":   resp["info"],
    })

# 3. Grade the episode
result = requests.post(f"{BASE}/grade", json={"episode_log": episode_log}).json()
print(result)

---

🏗️ Deploying to Hugging Face Spaces

1. Create a new Space with Docker as the SDK
2. Push this repository to the Space
3. HF Spaces automatically builds the Dockerfile and routes traffic to port 7860

---

📜 License

MIT