---
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
```bash
# 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](http://localhost:7860/docs)**

---

## 🐳 Running with Docker
```bash
# 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:**
```json
{ "level": 1, "max_steps": 200, "seed": 42 }
```

### `POST /step`
Take one action. Returns the new observation, reward, done flag, and info dict.

**Request body:**
```json
{ "action": 0 }
```

**Response:**
```json
{
  "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:**
```json
{
  "episode_log": [
    { "action": 1, "reward": -0.1, "done": false, "info": {} }
  ]
}
```

---

## 🤖 Quickstart Agent Loop
```python
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