AGENTS.md

Purpose: give coding agents one predictable place to learn how to build, test, lint, type check, route, and ship work in this repo without breaking things. Keep human onboarding in README.md.

Project profile

Name: Smoke-Alarm

Language: Python 3.11 or newer

Domain: smoke alarm compliance operations in Victoria AU

Top folders

agent Python package for CLI, services, optimizer, reports

gui Dispatcher UI

docs Runbooks and architecture notes

.github/workflows CI

scripts Local helpers

templates Report templates

apps_script Google Apps Script assets

Golden rules

Rebase on origin/main before any push.

Never commit conflict markers.

Never commit secrets. Service account JSON stays outside the repo.

Keep PRs small and focused. Update tests and docs with code changes.

Always run preflight before pushing.

Environment variables for local runs and CI (do not commit secrets)
OSRM_BASE_URL=http://localhost:5000

NOMINATIM_BASE_URL=https://nominatim.openstreetmap.org

GEOCODE_USER_AGENT=SmokeAlarmBot/1.0 (contact@example.com
)
GEOCODE_RPS=1
GOOGLE_SA_PATH=.secrets/service_account.json
APPRISE_URLS=
API_TOKEN=
PYTHONPATH=agent/src

Setup (use uv if available, else pip)
uv pip install --system -U pip
uv pip install --system -r requirements.txt || true
uv pip install --system ruff mypy pytest pytest-xdist coverage pytest-cov hypothesis bandit pip-audit deptry pipdeptree pre-commit nox
pre-commit install
pre-commit install --hook-type pre-push

Optional local OSRM for Australia. Prefer this to public demo.
Put australia-latest.osm.pbf in ./data then run:
docker run -t -v $(pwd)/data:/data osrm/osrm-backend osrm-extract -p /opt/car.lua /data/australia-latest.osm.pbf
docker run -t -v $(pwd)/data:/data osrm/osrm-backend osrm-partition /data/australia-latest.osrm
docker run -t -v $(pwd)/data:/data osrm/osrm-backend osrm-customize /data/australia-latest.osrm
docker run -p 5000:5000 -t -v $(pwd)/data:/data osrm/osrm-backend osrm-routed --algorithm mld /data/australia-latest.osrm

Daily preflight
ruff check . --fix
ruff format .
mypy .
pytest -n auto --cov=agent --cov-report=term
bandit -q -r agent -x tests
pip-audit -r requirements.txt --strict || true
deptry

Git hygiene
git fetch origin
git rebase origin/main
git grep -n -E '^(<{7}|={7}|>{7}||{7})' -- . && exit 1

Stable entry points
CLI route planning:
python -m agent.cli route --date YYYY-MM-DD --responses-file path/to/jobs.csv
Optional flags if present:
--vehicles N
--shift-start HH:MM
--shift-end HH:MM
--max-visits-per-tech N
--output pdf|csv|sheet

Service rules

Geocoding uses NOMINATIM_BASE_URL and GEOCODE_USER_AGENT and obeys GEOCODE_RPS.

Routing uses OSRM_BASE_URL. Do not use the public OSRM demo in production.

Sheets uses gspread with GOOGLE_SA_PATH. Share the sheet with that SA email.

Reports render with Jinja2 templates in templates and WeasyPrint for PDF.

UI starts with: streamlit run gui/streamlit_app.py

API if enabled runs at agent/src/agent/api/main.py and uses API_TOKEN header.

Coding standards

Ruff rules from pyproject.toml

mypy strict mode

Prefer pure functions and small modules

Log with structured messages and include correlation ids where helpful

Do not modify without reason

.github/workflows steps that enforce lint, type, tests

.secrets directory and any secret files

LICENSE

Commit and PR rules

Conventional commits

PR must include what changed, why, and test evidence

PR must pass CI and be up to date with origin/main

Self checks before opening a PR
ruff check . --fix && ruff format .
mypy .
pytest -n auto --cov=agent --cov-report=term
pip-audit -r requirements.txt --strict || true
git fetch origin && git merge-base --is-ancestor origin/main HEAD
git grep -n -E '^(<{7}|={7}|>{7}||{7})' -- . || echo "No conflict markers"

Nested AGENTS.md
Add scoped AGENTS.md files inside key subfolders to refine rules for that area. The root file stays the source of truth. Keep nested files short and consistent.