laivision 0.1.8

LAI: a platform to train and deploy AI vision models — datasets, annotation, training, and evaluation.

LAI

laivision.dk — project site, workflow overview, and tutorials.

Self-hosted computer vision studio: datasets, SAM-assisted annotation, training (YOLO / MMYOLO / RT-DETR), evaluation, and export.

Install a small CLI from PyPI, pull pre-built images from Docker Hub, and run everything with lai. No git clone required.

Tested on: Linux (Ubuntu) and Windows 10/11 (Docker Desktop + WSL2).

---

Requirements

Requirement	Notes
OS	Linux or Windows 10/11 (see platform notes below)
Docker Engine + Compose v2.24+	docker compose version must work
Python 3.10–3.12	For the lai CLI only — not for running the app itself
RAM	8 GB minimum · 16 GB+ recommended (32 GB with GPU tier)
Disk	~5 GB (CPU stack) · ~20–30 GB (GPU images + models)
Browser	For lai install-gui and the studio UI
NVIDIA GPU (optional)	Training, auto-annotate, SAM — GPU tier + Container Toolkit (Linux) or WSL2 GPU passthrough (Windows)

You do not need Node.js, a git checkout, or local image builds for the quick start.

Linux

• Docker Engine + Compose plugin
• Install CLI with pipx or a venv (recommended on Debian/Ubuntu — do not use system pip; PEP 668)

Windows

• Docker Desktop with WSL2 backend
• lai install-gui works in any browser; terminal lai install needs Git Bash or WSL
• GPU tier: enable WSL2 integration in Docker Desktop and install NVIDIA drivers for WSL

---

Quick start

flowchart LR
  A["① pip install laivision"] --> B["② lai install-gui"]
  B --> C["③ lai up"]
  C --> D["④ lai download-models"]
  D --> E["Open localhost:8089"]

① Install the CLI

pip install laivision
# recommended:  pipx install laivision

Installs the lai command and embeds Docker Compose files inside the package. Your settings live in ~/.config/lai/.env (not in site-packages), so upgrades do not overwrite them.

---

② First-time setup

lai install-gui

Opens a browser wizard on http://127.0.0.1:… where you choose:

Setting	Default	Purpose
Data directory	~/lai-data	Databases, datasets, projects, model cache
Web port	8089	UI in your browser
GPU tier	off	Enables worker-gpu + sam_service (NVIDIA required)
SAM 3 folder	~/lai-data/sam3-models	Optional checkpoint path (SAM 2 works without it)
DINOv3 folder	~/lai-data/dinov3-models	INSID3 weights (ViT-B from Meta CDN or python backend/scripts/download_dinov3_models.py)

Terminal alternative: lai install or lai install --yes for non-interactive defaults.

---

③ Start the stack

lai up

• Pulls images from Docker Hub (luluray/lai-*) if they are not local yet
• Starts database, API, workers, and web UI
• First run may take several minutes while images download

Then run step ④ (lai download-models) before training or auto-annotate. You can open http://localhost:8089 (or the port you chose) while weights download.

lai down          # stop containers
lai doctor        # version, Docker checks, bundle path
lai upgrade       # after pip install -U laivision

---

④ Download foundation models (required — run after lai up)

lai download-models

Downloads the weights LAI needs for training, auto-annotate, and related workflows into your data directory ($LAI_DATA_DIR/models and ai_models/). The studio is not fully usable until this finishes — without these files, training and auto-annotate will fail or hang waiting for models.

Run it once after the stack is up (containers must be running). You can narrow what is fetched:

lai download-models --yolo yolov8n.pt      # single Ultralytics weight
lai download-models --mmyolo minimal         # MMYOLO pretrained checkpoints
lai download-models --depth minimal          # depth estimation ONNX

Use lai download-models --help for the full matrix. Re-run anytime to add more weights.

---

Optional extras

SAM 3 — SAM 2 is included. For SAM 3, place a checkpoint (e.g. from Hugging Face) at the path from the wizard, then:

lai restart sam_service

INSID3 (DINOv3) — From example segmentation uses DINOv3 ViT-B weights in the folder from install (DINOV3_WEIGHTS_HOST_PATH). Default file: dinov3_vitb16_pretrain_lvd1689m-73cec8be.pth (~330 MB). Download via python backend/scripts/download_dinov3_models.py or Meta CDN. Do not use a ViT-S (vits16, 384-dim) file renamed as vitb16. Then restart sam_service.

GPU check (if GPU tier is enabled):

docker compose exec worker-gpu nvidia-smi

---

Where things live

Path	Contents
~/.config/lai/.env	Ports, data dir, Docker image tags
~/lai-data/ (default)	Postgres/Redis/Mongo data, projects, models
~/lai-data/backups/	Manual backup snapshots (see below)
PyPI package lai/bundle/	Read-only compose files (do not edit)

---

Backup & restore

LAI can back up PostgreSQL and project files (/app/projects) to local disk when you click Run Backup in Settings. This is separate from the JSON/ZIP export in Settings → Database Manager.

Location

Host	Container
$LAI_DATA_DIR/backups/ (default ~/lai-data/backups/)	/app/backups

To store backups elsewhere, add BACKUP_PATH=/your/path to ~/.config/lai/.env, then run lai down and lai up. The path is mounted into backend and worker containers.

Create a backup

1. Open Settings → Backups.
2. Subdirectory is optional — leave empty to use the root of the backup directory (e.g. ~/lai-data/backups/).
3. Set retention (days), then Save Settings.
4. Click Run Backup, or enable Automatic backups with a frequency (hours).

Each snapshot is a folder like backup_YYYYMMDD_HHMMSS/ containing database/*.dump and project files.

Backups run on worker-general (not the API). Automatic runs are triggered by Celery Beat every 15 minutes when the schedule is due.

Restore from a snapshot

1. Stop training and other long-running jobs.
2. In Settings → Backups, find a completed snapshot and click Restore.
3. Choose database and/or project files, confirm, and type RESTORE.
4. When finished, verify projects and data in the UI.
5. Previous project files are renamed to projects.pre_restore_* under your data directory — delete that folder once you are satisfied.

Restore the most recent completed snapshot when possible. Older incremental snapshots may be incomplete if newer backups were deleted.

Disaster recovery

Copy the entire $LAI_DATA_DIR directory off-host regularly (external drive, NAS, etc.). Off-site sync (S3, restic) is not built into LAI yet.

Not included in snapshot backup v1: FiftyOne/MongoDB metadata, Redis, training runs (/app/runs), or legacy /app/data paths. Use database export or separate mongodump if you need those.

---

Advanced setup

Git checkout, building images locally, running tests, maintainer releases → see README_advanced.md.

---

License

AGPL-3.0 — bundled ML runtimes (YOLO, MMYOLO, SAM) have additional upstream licenses. Details in README_advanced.md#license.