README.md

---
title: Traffic Control Env
emoji: 🚦
colorFrom: green
colorTo: blue
sdk: docker
app_port: 7860
tags:
  - openenv
  - reinforcement-learning
  - traffic-control
  - fastapi
---

# Indian Traffic Signal OpenEnv

A deterministic, seedable RL environment for Indian urban traffic signal control. The simulator models mixed traffic, pedestrian pressure, rain, emergency vehicles, unsafe switching, and hidden driver behavior.

## Observation Space

`GET /state` and every `step()` result return:

- lane-wise queues for cars, bikes, autos, buses, and trucks
- lane waiting times
- current signal phase and time since last phase switch
- pedestrian count and pedestrian waiting time
- emergency vehicle presence, lane, type, and wait time
- rain level
- seeded random inflow from the most recent tick

Hidden dynamics include driver aggression, random blockage probability, and peak-hour multiplier. These affect traffic flow but are exposed only in `info` for debugging and grading transparency.

## Action Space

Discrete actions:

- `NS_GREEN`
- `EW_GREEN`
- `LEFT_PRIORITY`
- `PEDESTRIAN_CROSS`
- `EXTEND_GREEN`
- `EMERGENCY_OVERRIDE`
- `ALL_RED`

The environment penalizes unsafe rapid switching, emergency override without an emergency, and pedestrian phases without demand.

## Tasks

- `single_intersection`: easy, balanced four-way control.
- `rush_hour`: medium, heavier asymmetric commuter traffic and rain.
- `emergency_priority`: hard, frequent emergency vehicles and stricter emergency handling.

## Setup

```bash
pip install -r requirements.txt
uvicorn api:app --host 0.0.0.0 --port 8000
```

Run tests:

```bash
pytest -q
```

Run the submission validator once the Hugging Face Space is deployed:

```bash
bash scripts/validate-submission.sh https://your-space.hf.space .
```

Run the baseline inference script after starting the API:

```bash
python inference.py --task-id single_intersection --seed 42 --steps 30
```

## API

- `POST /reset`
- `POST /step`
- `GET /state`
- `GET /tasks`
- `POST /grader`
- `GET /baseline`

## Baseline Scores

Scores are reproducible for a fixed seed through `GET /baseline?seed=42`. The baseline is intentionally simple: fixed cycles, queue switching, and immediate emergency override.