# @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

```bash
# 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)

```bash
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` |