docs/ROADMAP.md

# AVIS — Build Roadmap

Strategy: **vertical slice first.** Get one violation (helmet, Tier A) flowing end-to-end
— upload → detect → graph → rule → annotate → store → see it on the dashboard — before
adding breadth. A thin working pipeline beats six half-built stages at demo time. Each
phase ends with something runnable and verifiable.

Mapping to the problem statement's required tasks is noted as `[PS: …]`.

---

## Phase 0 — Skeleton (≈2h)
- FastAPI app, `POST /images` (upload) + `GET /violations` + `GET /violations/{id}`.
- `core/schemas/` Pydantic models for every stage payload (image, detection, graph,
  candidate, violation).
- SQLite via SQLModel; `storage/` abstraction (metadata + image file save/load).
- Health check + a stub pipeline that just stores the image. `pytest` green, `ruff`/`mypy` clean.
- **Verify:** upload an image via Swagger UI, see a record in SQLite.

## Phase 1 — Vertical slice: helmet end-to-end (≈5h)  `[PS: Detection, Violation Detection, Classification, Evidence]`
- Stage 3 **Detect**: Ultralytics YOLO (COCO) → person/motorcycle/etc.
- Stage 4 **Scene Graph**: rider↔motorcycle association by geometry; graph builder + tests.
- Stage 5 **Helmet** attribute (fine-tuned YOLO/classifier on rider crops).
- Stage 6 **Rule Engine**: `helmet_rule()` pure function + unit tests.
- Stage 10 **Evidence Composer**: annotated image (boxes + label) saved to filesystem.
- Minimal dashboard: upload + results table + annotated image view.
- **Verify:** upload a no-helmet image → violation row + annotated image on the dashboard.

## Phase 2 — Breadth on Tier A + plates (≈5h)  `[PS: Vehicle/Road-User Detection, License Plate Recognition]`
- Triple-riding rule (count `rides` edges) + tests.
- Vehicle classification surfaced from detector classes.
- **fast-alpr** plate detection + OCR + Indian-plate regex correction; attach plate to graph.
- **Verify:** triple-riding image flagged; plate text shown and regex-validated.

## Phase 3 — Confidence routing + VLM verification (≈5h)  `[PS: Classification + confidence scores]`
- Stage 7 **Fuse + Route**: tier-aware thresholds from config; abstain path.
- `core/llm/` provider-agnostic client → **Gemini Flash free tier**; strict JSON contract.
- Stage 8 **VLM Verify** on routed candidates; cache by `evidence_hash`; quota-safe fallback.
- Confidence + reason persisted on every violation.
- **Verify:** an ambiguous case hits the VLM and returns reason+confidence; a clear Tier-A
  case auto-confirms without a VLM call (check the cache/logs).

## Phase 4 — Tier C (calibration) + legal + robustness (≈5h)  `[PS: Preprocessing, Evidence]`
- Stage 1 **Quality gate** (blur/exposure) → `undeterminable` abstain path.
- Stage 2 **Preprocess** (CLAHE, denoise, low-light).
- Traffic-light state + per-camera calibration (`configs/`): stop-line / no-parking
  polygons via `shapely`; stop-line & illegal-parking + red-light **candidate** rules.
- Stage 9 **Legal map**: static violation→section→fine table.
- Wrong-side: low-confidence candidate only.
- **Verify:** calibrated sample image yields a stop-line candidate routed to review with
  the correct legal section; a blurry night image abstains.

## Phase 5 — Analytics, search, review queue (≈4h)  `[PS: Analytics & Reporting]`
- Dashboard: violation trends/charts (Chart.js), searchable records, summary export.
- Human-review queue UI for low-confidence/Tier-C cases (approve/reject → audit trail).
- **Verify:** stats reflect stored data; a reviewer can resolve a queued case.

## Phase 6 — Evaluation harness (≈4h)  `[PS: Performance Evaluation]`
- Scripts: component P/R/F1/mAP on public datasets; end-to-end confusion matrix +
  per-image false-positive rate; latency/throughput; auto/VLM/human split + ablation.
- **Verify:** `python -m eval.run` prints the metrics table used in the pitch.

## Phase 7 — Polish & demo (≈4h)
- One-command `docker compose up`; pre-cache VLM responses for demo images.
- 3–4 curated demo images (incl. one the system deliberately abstains on).
- Pitch deck from `docs/DESIGN.md` §14; README with screenshots.

---

## Definition of done (every phase)
`pytest -q` green · `ruff check` + `mypy` clean · the phase's **Verify** step demonstrated
with real output · no fabricated results on the demo path (stub explicitly and say so).

## Cut-scope order if time runs short
Drop in this order: optional RAG → wrong-side (Tier D) → analytics polish → seatbelt
(Tier B) → calibration (Tier C). **Never cut** the helmet/triple-riding vertical slice,
confidence routing, or the abstain path — those are the demo and the thesis.