SADHANA14/alphaBetaGamma

AlphaBetaGamma (Docker Space)

This repository packages a lightweight urban traffic signal control environment as an HTTP API (FastAPI) plus a reference hybrid policy (rules → LLM → greedy fallback) and an inference runner that drives the environment via its API.

The Hugging Face Space runs the API server from the Dockerfile.

What’s included

• —Environment server: server.py (FastAPI + Pydantic models)
• —Traffic simulator: simulator/ (grid of intersections, vehicle spawning, movement, reward signals)
• —Agent policy: agent/policy.py (min-green, emergency priority, fairness override, optional LLM, greedy fallback)
• —Reward utilities: agent/reward.py (step reward + episode score)
• —Client/inference: inference.py (runs tasks 1–3 by calling the server)
• —Runtime smoke test: validate_runtime.py (starts server locally and runs inference.py with LLM disabled)
• —Task grader: agent/grader.py (deterministic episode scoring + success threshold)
• —Logged runner: run_logged.py (runs local server + inference and writes a combined log file)

Tasks

The environment supports three tasks:

• —Task 1 (easy): 1x1 grid, max_steps=25
• —Task 2 (medium): 2x2 grid, max_steps=35
• —Task 3 (hard): 3x3 grid, max_steps=45

HTTP API

The Space exposes a JSON API on port 7860.

GET / and GET /health and GET /ping

• —GET / returns a small JSON payload listing the available endpoints.
• —GET /health returns {"status":"ok"} for liveness checks.
• —GET /ping returns {"status":"ok"} for OpenEnv-style ping checks.

POST /reset

Initializes a new episode.

Body:

{"task_id": 1, "seed": 42}

• —task_id: 1 (easy), 2 (medium), 3 (hard)
• —seed: optional for reproducibility

Returns: ResetResponse with observation (global state snapshot).

POST /step

Advances the simulator by one step.

Body:

{
	"actions": [
		{"intersection_id": 0, "phase": 0}
	]
}

• —phase: 0 = North/South green, 1 = East/West green

Returns: StepResult containing observation, reward (normalized to [0,1]), done, and info.

GET /state

Returns the current GlobalState. If you haven’t called /reset yet, the server returns 409.

GET /docs

FastAPI Swagger UI.

Run locally (Python)

pip install -r requirements.txt
uvicorn server.app:app --host 0.0.0.0 --port 7860

In a second terminal:

curl -sS -X POST http://127.0.0.1:7860/reset \
	-H "Content-Type: application/json" \
	-d '{"task_id":1,"seed":42}'

Run the reference inference loop:

export ENV_BASE_URL=http://127.0.0.1:7860
python3 inference.py

Run against the live Space

The Space base URL is:

• —https://sadhana14-alphabetagamma.hf.space/

Example:

curl -sS -X POST https://sadhana14-alphabetagamma.hf.space/reset \
	-H "Content-Type: application/json" \
	-d '{"task_id":1,"seed":42}'

Run locally (Docker)

docker build -t alphabetagamma .
docker run --rm -p 7860:7860 alphabetagamma

Validate under 2 vCPU / 8GB

Run the server with hard limits:

docker run --rm -p 7860:7860 --cpus=2 --memory=8g --name opentrafficenv_local alphabetagamma

Then drive it with the client (LLM disabled for deterministic runtime):

ENV_BASE_URL=http://127.0.0.1:7860 DISABLE_LLM=1 python3 inference.py

Write a combined run log

This starts a local server, runs inference.py, and captures both into a single log file:

python3 run_logged.py --disable-llm 1 --log runs/disable_llm_1.log

Configuration (env vars)

See .env.example for a template.

• —ENV_BASE_URL: where inference.py calls the environment (default https://sadhana14-alphabetagamma.hf.space/)
• —DISABLE_LLM: set to 1 to force the policy to avoid LLM calls
• —HF_TOKEN: API key used by the OpenAI-compatible client (used when LLM is enabled)
• —OPENAI_API_KEY: supported alias for HF_TOKEN
• —API_BASE_URL: OpenAI-compatible base URL (default https://api.openai.com/v1)
• —MODEL_NAME: model name string used by the policy client
• —VALIDATION_TIMEOUT_S: timeout for validate_runtime.py (default 1200)

Notes

• —The environment uses a minimum green time constraint (prevents flickering).
• —The simulator returns a normalized reward per step; agent/reward.py can compute a reward from info as a fallback.
• —See openenv.yml for an API/spec summary (base URL, endpoints, and model schema).

Repository layout

.
├── Dockerfile
├── server.py
├── models.py
├── inference.py
├── validate_runtime.py
├── requirements.txt
├── agent/
└── simulator/