ML / Computer-Vision design docs

Owner: Sophia Mann · Agent D bucket · Last updated: 2026-05-12

This directory holds the ML/CV-pipeline design docs for the LBZF Phase I deployment (Pereira, July 2026 go-live) and the forward-looking Phase II / III plans. Sister buckets live in ../hardware/, ../../business/, and the front-end / back-end docs under the technical/ tree.

Scope

Phase I (locked per ADRs 001–006):

• YOLOv8n + TensorRT person detection on Jetson Orin Nano Super (ADR-003)
• 2 PoE cameras — Amcrest IP8M-2779EW-AI varifocal (ADR-001) — H.264 sub-stream downscaled on the Jetson to 640×480; inference at 3–5 fps per ADR-004
• Cycle-time event extraction per workstation in the Angela module
• SQLite event store (CV writer writes directly; see cycle-event-detection.md) + FastAPI dashboard + Excel export
• Validation against Ronald Gonzalez Suarez’s stopwatch ground truth

Phase II:

• Behavioral monitoring (phone use, eating, talking, unjustified absence)
• Garment-type / operation classification
• Likely Jetson Orin NX 16GB / AGX Orin 32GB tier hardware (compute tier not finalized; Nano Super’s 8 GB likely insufficient for behavioral models)
• ~20 cameras

Phase III:

• Scale to all 4 modules (Angela, Carmenza, Camisetas, Empaque)
• Generalize beyond Ref22 Slim reference

Reading order

For a reviewer (Andrew, ITBA, IEEE referee), read in this order:

1. cycle-event-detection.md — what a “cycle event” means in CV terms, how the system decides a cycle started or ended, all the failure cases.
2. roi-calibration.md — how the system knows where each workstation’s bounding box lives in each camera frame, and how that survives a camera bump.
3. training-and-finetuning.md — whether to fine-tune the off-shelf YOLOv8n, dataset construction from Ronald’s 41 videos, compute (AWS-vs-laptop) recommendation.
4. validation-methodology.md — the IEEE paper’s experimental design. Agreement metrics, ground-truth source, IRB / consent.
5. failure-modes-and-monitoring.md — when the pipeline silently lies. Self-monitoring and alerting.
6. phase-ii-preview.md — what Phase II adds and what Phase I must capture now to make Phase II easier later.
7. reproducibility-and-artifacts.md — what a paper reviewer should be able to download to reproduce the results.

_template.md is the doc skeleton used by all of the above.

Document conventions

• All docs follow _template.md’s structure: Context / Goals / Non-goals / Proposed approach / Alternatives / Open questions / Cross-bucket deps / Self-critiques / Rollout / Paper alignment.
• Open questions must name an owner: Sophia / Andrew / Ronald / Armando / ITBA / Mariana.
• Numbers, thresholds, and confidence intervals are required for “Proposed approach” sections. If unknown, mark OPEN: <q, owner>.
• Cited papers are tagged either [verified] (URL or DOI found via WebSearch on 2026-05-10) or [needs-lit-review] (worth searching but not yet confirmed).

Cross-bucket map (one line each)

• Agent A — frontend: consumes cycle_events and standard_times; renders the live dashboard and color-coded efficiency. Owns the calibration UI surface (when one exists).
• Agent B — backend: SQLite schema, ingestion path from the inference loop, export to Excel. Owns the event-log API.
• Agent C — hardware: camera placement, lens choice, lighting, network/PoE, Jetson thermals, compute headroom on the Orin Nano.
• Agent E — business / legal: IRB-equivalent posture, Colombian Law 1581/2012 consent, LBZF IP, open-source posture for model + dataset.

What this bucket explicitly does NOT cover

• The Astro/Cloudflare landing-page deployment (src/pages/index.astro) — owned by the frontend bucket.
• Auth0, Cloudflare Workers, or any production-stack devops (Andrew’s “full prod stack day 1”) — owned by Agent C.
• The plant-floor financial / efficiency-improvement business case — owned by Agent E.
• LBZF org-chart politics or Mariana-as-aunt dynamics — owned by Agent E.

Status

All docs in this bucket are draft as of 2026-05-10 and intended for round-2 critique by sibling agents.