julian
6933406ae3
Skeleton of the host-side vision service per the packaging decision: a Python/FastAPI app at apps/vision/, uv-managed, wired into the Turbo graph via a thin package.json shim (dev/lint/test/build → uv/uvicorn/ruff/pytest). A per-package turbo.json sets build outputs [] so the no-op build is warning-free. Endpoints: GET /health (readiness + model version) and POST /analyze (raw octet-stream body, so Node POSTs Snapshot.bytes directly; empty→400, oversize→413, recognizer-not-ready→503). The recognizer is a Protocol with a StubRecognizer (no models, boots/tests offline — the dev/CI default) and a FastAlprRecognizer (the real MIT YOLOv9+CCT/ONNX stack, lazily imported; missing models ⇒ ready=False, not a crash) — the device-adapter pattern applied to the model. fast-alpr + onnxruntime are an optional `alpr` extra, so `uv sync` needs no model download. Verified: turbo run lint|test|build includes @parking/vision and stays green; uv run mypy strict-clean; uvicorn boots and serves /health + /analyze live; pnpm workspace 6→7. Not built yet: the Node VisionClient adapter, a Dockerfile + model fetch, and Job 2 (vehicle verification). Updates the packaging decision (As-scaffolded) + log. Claude-Session: https://claude.ai/code/session_01Xcm6ikLgGoCxxHrxtjkk5V
2.4 KiB
@parking/vision — host-side ANPR / vehicle-verification service
A separate process (Python + FastAPI) the Node backend calls over localhost HTTP with a camera snapshot, returning a licence-plate read (and, later, vehicle-attribute verification — the anti-plate-spoofing witness). Recognition is advisory, never the sole authority to open a barrier: if this service is down or unsure, the host falls back to the ticket path.
Lives inside the Turborepo at apps/vision/ but is not a JS package — Python deps are managed by
uv/pyproject.toml; the package.json is a thin shim so turbo run lint/test includes it. See
wiki/decisions/vision-service-packaging.md and wiki/entities/opencv-anpr-service.md.
Run
# from apps/vision/ — install the light core (boots in stub mode, no model downloads)
uv sync
# dev server with reload (or: pnpm --filter @parking/vision dev)
uv run uvicorn vision_service.app:app --reload --port 8089
# checks
uv run ruff check .
uv run pytest -q
Enable the real recognizer (fast-alpr)
uv sync --extra alpr # installs fast-alpr + onnxruntime (downloads model weights)
VISION_RECOGNIZER=fast_alpr uv run uvicorn vision_service.app:app --port 8089
fast-alpr is MIT (YOLOv9 detector + CCT OCR on ONNX Runtime). Swap VISION_OCR_MODEL to the 40+
country European model to benchmark Albanian plates. For GPU/NPU, install onnxruntime-gpu /
-openvino / -directml instead of onnxruntime.
API
GET /health→{ status, recognizer, ready, model_version, detail? }POST /analyze(body = raw image bytes,Content-Type: application/octet-stream) →{ plate: {text, confidence, bbox}|null, plates[], vehicle: null, low_confidence, model_version, took_ms }
The Node side POSTs Snapshot.bytes directly (no multipart). vehicle is scaffolded but not yet
populated — fast-alpr is plate-only; the vehicle stage (Job 2) is built later on the same runtime.
Config (env, prefix VISION_)
| Var | Default | Meaning |
|---|---|---|
VISION_RECOGNIZER |
stub |
stub (no models) or fast_alpr (real) |
VISION_PORT |
8089 |
listen port |
VISION_DETECTOR_MODEL |
yolo-v9-t-384-license-plate-end2end |
fast-alpr detector |
VISION_OCR_MODEL |
cct-xs-v2-global-model |
fast-alpr OCR |
VISION_MIN_CONFIDENCE |
0.5 |
below this → low_confidence=true |