Imported from demiolawunmi/CGI-ML-Project (AGENTS.md). Install upstream with npx skills add demiolawunmi/CGI-ML-Project. Copyright stays with the author.

Repository Guidelines

Project Structure & Module Organization

This monorepo contains two Python proof-of-concept applications:

• hotspot_app_web/ is the Toronto collision-hotspot Flask app. Its web entry point is app.py; data preparation and model training live in pipeline.py; computer-vision scripts are camera_scan.py and vision_demo.py. UI assets are in templates/ and static/; source datasets are in data/; saved model outputs and camera images are in prebuilt/.
• danforth_ast_poc/ is the adaptive-signal-timing POC. app/app.py serves the UI, core/ contains controller logic, vision/ contains vehicle-counting code, and simulation/, demand/, and baseline/ support the SUMO scenario.

Keep generated videos, uploads, checkpoints, and large artifacts out of unrelated source changes.

Build, Test, and Development Commands

Run commands from the relevant project directory using a Python 3.10+ virtual environment.

cd hotspot_app_web && pip install -r requirements.txt && python app.py
cd danforth_ast_poc && pip install -r app/requirements.txt && python app/app.py
cd danforth_ast_poc/core && python test_controller.py

The first two commands start local Flask apps on ports 5000 and 5001 respectively. The controller harness simulates one hour of traffic and asserts signal safety constraints. The hotspot pipeline can also be run directly with python pipeline.py when its required data/ files are available.

Coding Style & Naming Conventions

Follow the established Python style: four-space indentation, snake_case for functions and variables, and PascalCase for classes. Keep route handlers thin; move reusable model, simulation, and vision logic into their corresponding modules. Use clear dataset keys such as tmc_summary and units in names such as duration_s.

There is no configured formatter or linter. Match nearby code, keep imports grouped near the top, and avoid broad refactors mixed with behavioral changes.

Testing Guidelines

Add focused tests beside the logic they cover, following the existing test_controller.py pattern. Test safety rules, data validation, and deterministic transformations without requiring models, camera footage, or external data. Run the controller harness before changing danforth_ast_poc/core/controller.py; smoke-test affected Flask routes and uploads for UI or API changes. No coverage threshold is configured.

Commit & Pull Request Guidelines

The available history uses short imperative summaries (for example, Add existing ML projects to monorepo). Use the same style: Fix camera scan path rather than fixed paths. Keep commits scoped. Pull requests should explain the affected POC, validation performed, data/model artifact changes, and any assumptions. Include screenshots or a short video for visible UI, map, or dashboard changes, and link the relevant issue when one exists.