spec_version: 1
name: traffic-env
version: "1.0.0"
description: >
  Smart City Traffic Flow -- OpenEnv RL environment for adaptive traffic
  signal control. An agent controls signal phases at urban intersections
  to minimise vehicle waiting time and maximise throughput. Simulates
  real-world sensor data (queue lengths, wait times) from road cameras
  and inductive loop detectors.

type: environment
runtime: docker

app:
  port: 7860
  module: server.app
  object: app

tasks:
  - id: easy
    name: "Easy — single intersection"
    description: "Single intersection, 4 lanes, steady vehicle arrival rate"
    difficulty: easy
    max_steps: 100
    reward_range: [-1.0, 1.0]
    grader:
      id: easy_score
      enabled: true
      endpoint: /grader
      method: POST
      payload:
        task_id: easy
    graders:
      - id: easy_score
        enabled: true
        endpoint: /grader
        method: POST
        payload:
          task_id: easy
    env_vars:
      TASK_LEVEL: easy

  - id: medium
    name: "Medium — urban corridor"
    description: "3-intersection urban corridor with rush-hour demand spike"
    difficulty: medium
    max_steps: 200
    reward_range: [-1.0, 1.0]
    grader:
      id: medium_score
      enabled: true
      endpoint: /grader
      method: POST
      payload:
        task_id: medium
    graders:
      - id: medium_score
        enabled: true
        endpoint: /grader
        method: POST
        payload:
          task_id: medium
    env_vars:
      TASK_LEVEL: medium

  - id: hard
    name: "Hard — 3×3 grid"
    description: "3x3 grid of 9 intersections with random incidents"
    difficulty: hard
    max_steps: 300
    reward_range: [-1.0, 1.0]
    grader:
      id: hard_score
      enabled: true
      endpoint: /grader
      method: POST
      payload:
        task_id: hard
    graders:
      - id: hard_score
        enabled: true
        endpoint: /grader
        method: POST
        payload:
          task_id: hard
    env_vars:
      TASK_LEVEL: hard

action_space:
  type: discrete_composite
  fields:
    - name: action_type
      type: enum
      values: [extend_green, next_phase]
    - name: intersection_id
      type: int
      min: 0

observation_space:
  type: structured
  fields:
    - name: intersections
      type: list
    - name: total_waiting_vehicles
      type: int
    - name: total_avg_wait
      type: float
    - name: throughput_last_step
      type: int
    - name: reward
      type: float
    - name: done
      type: bool

reward:
  type: dense
  range: [-1.0, 1.0]
  description: "reward = 0.6*throughput_bonus + 0.4*wait_penalty, fired every step"

metadata:
  author: "Anika Jain"
  license: MIT
  tags: [traffic, urban-planning, real-world, rl, openenv, smart-city]
  huggingface_space: "anidoesdev/traffic-env"