diff --git a/docs/Architecture/README.md b/docs/Architecture/AI-Architecture.md similarity index 87% rename from docs/Architecture/README.md rename to docs/Architecture/AI-Architecture.md index 9a00ab7..3dae5e8 100644 --- a/docs/Architecture/README.md +++ b/docs/Architecture/AI-Architecture.md @@ -15,6 +15,8 @@ Dit document beschrijft uitsluitend de **AI-componenten** en hun integratie binn - De API-laag die de AI-functionaliteit aanbiedt - De gebruikte technologieën en frameworks +Voor een deep-dive in het `smart_gestures` package, model lifecycle en alle CLI-opties, zie [AI-Packages.md](./AI-Packages.md). + ## Overzicht Architectuur ### High-level AI-architectuur @@ -135,7 +137,10 @@ De 21 landmarks representeren: MediaPipe wordt gebruikt om keypoints te extraheren uit een dataset van afbeeldingen en video-frames. Deze keypoints worden vervolgens genormaliseerd en doorgegeven aan de deep learning modellen voor inferentie. MediaPipe is eveneens geïntegreerd in de FastAPI backend via een dedicated router: -Het `/keypoints/` REST-endpoint accepteert een afbeelding (multipart/form-data), verwerkt deze met MediaPipe, en retourneert de landmarks als JSON: + +- `POST /keypoints/hands`: accepteert een afbeelding (multipart/form-data) en retourneert 21 hand-landmarks als JSON. +- `POST /keypoints/pose`: accepteert een afbeelding en retourneert een `LSTMFrame` met pose + linker/rechterhand landmarks voor sequentiële modellen. +- `POST /keypoints/` (root): deprecated; redirect naar `/keypoints/hands`. ```json { @@ -168,6 +173,7 @@ Het ASL-model herkent **35 klassen** (American Sign Language alfabet + cijfers): - **Letters**: a-z (zonder bewegingen) - **Cijfers**: 0-9 - **Totaal**: 35 statische gebaren +- **Opmerking**: De letter `q` ontbreekt in de huidige dataset omdat MediaPipe geen stabiele keypoints kon extraheren uit de gebruikte Kaggle-bron. Dit gebaar volgt zodra er betrouwbare trainingsdata beschikbaar is. De klassen zijn gedefinieerd in `notebooks/package/smart_gestures/alphabet/asl_model/data/classes.json`. @@ -184,7 +190,7 @@ Deze normalisatie maakt het model **invariant** voor handpositie en -grootte. #### Integratie (ASL Model) - **Package**: `smart_gestures.alphabet.asl_model.ASLModel` -- **API-endpoint**: `/asl/predict` (POST) +- **API-endpoint**: `/alphabet/asl/predict` (POST) - **Input**: JSON met lijst van 21 landmarks - **Output**: Voorspelde klasse (string) @@ -231,7 +237,7 @@ Hoewel de **modelarchitectuur identiek** is, zijn de modellen getraind op versch #### Integratie (VGT Model) - **Package**: `smart_gestures.alphabet.vgt_model.VGTModel` -- **API-endpoint**: `/vgt/predict` (POST) +- **API-endpoint**: `/alphabet/vgt/predict` (POST) - **Input**: JSON met lijst van 21 landmarks - **Output**: Voorspelde klasse (string) @@ -250,8 +256,8 @@ Hoewel de **modelarchitectuur identiek** is, zijn de modellen getraind op versch ```label Input: Sequentie van 40 frames × 258 features - LSTM Layer 1: 128 hidden units + Dropout(0.4) - LSTM Layer 2: 128 hidden units + Dropout(0.4) + LSTM Layer 1: 128 hidden units + Dropout(0.2) + LSTM Layer 2: 128 hidden units + Dropout(0.2) Fully Connected: 128 → 5 klassen Output: 5 woordklassen + confidence score ``` @@ -298,7 +304,7 @@ Deze preprocessing behoudt **temporele informatie** en maakt het model robuust t #### Integratie (LSTM Model) - **Package**: `smart_gestures.gestures.lstm_model.LSTMModel` -- **API-endpoint**: `/lstm/predict` (POST) +- **API-endpoint**: `/gestures/lstm/predict` (POST) - **Input**: JSON met sequentie van frames (elk frame bevat 258 features) - **Output**: Voorspelde woord + confidence score (0.0 - 1.0) @@ -313,11 +319,11 @@ Deze preprocessing behoudt **temporele informatie** en maakt het model robuust t | Technologie | Versie | Rol | Voordelen | |------------|--------|-----|-----------| -| **PyTorch** | 2.3 | Deep learning framework | - Flexibele modelarchitectuur; - Dynamische computation graphs; - Sterke community support; - Eenvoudige model serialisatie (.pth) | -| **MediaPipe** | 0.10 | Computer vision + keypoint extraction | • Real-time performance; • Pre-trained hand detection; • Robuuste landmark tracking; • Cross-platform support | -| **NumPy** | 1.26 | Numerieke operaties | Efficiënte array-operaties; Basis voor PyTorch tensors; Data preprocessing | -| **OpenCV (cv2)** | 4.11 | Image processing | Image decoding (JPEG/PNG); Color space conversies (BGR↔RGB); Basis image manipulatie | -| **Pandas** | 2.3 | Data handling (training) | Dataset management; CSV/JSON I/O; Data augmentatie | +| **PyTorch** | 2.7.0 | Deep learning framework | - Flexibele modelarchitectuur; - Dynamische computation graphs; - Sterke community support; - Eenvoudige model serialisatie (.pth) | +| **MediaPipe** | 0.10.21 | Computer vision + keypoint extraction | • Real-time performance; • Pre-trained hand detection; • Robuuste landmark tracking; • Cross-platform support | +| **NumPy** | 1.26.4 | Numerieke operaties | Efficiënte array-operaties; Basis voor PyTorch tensors; Data preprocessing | +| **OpenCV (cv2)** | 4.11.0.86 | Image processing | Image decoding (JPEG/PNG); Color space conversies (BGR↔RGB); Basis image manipulatie | +| **Pandas** | 2.3.3 | Data handling (training) | Dataset management; CSV/JSON I/O; Data augmentatie | ### Package Management @@ -427,7 +433,7 @@ Geen code-wijzigingen nodig in de API—de `/lstm/classes` endpoint leest automa #### Resource-gebruik -- **Memory**: ~200-300 MB per model geladen (acceptabel voor smart glasses) +- **Memory**: ~200-300 MB per model geladen - **CPU**: Single-threaded inferentie (mogelijkheid voor threading bij hogere throughput) - **GPU**: Niet vereist (belangrijk voor edge devices) @@ -463,7 +469,7 @@ Mogelijke test-coverage: - **Training metrics**: Accuracy, loss curves (zie `notebooks/training/`) - **Validation**: Hold-out test set evaluatie -- **Calibration**: Confidence scores afstemmen op echte accuratesse (VGT model gebruikt Brier score regularisatie) +- **Calibration**: Confidence scores afstemmen op echte accuratesse ## Conclusie @@ -482,7 +488,7 @@ De architectuur is ontworpen met **schaalbaarheid** en **onderhoudbaarheid** in **Document-informatie**: -- **Versie**: 1.1 +- **Versie**: 1.2 - **Datum**: December 2025 - **Auteurs**: Lynn Delaere - **Contact**: Zie [GitHub repository](https://github.com/vives-project-xp/Signapse) diff --git a/docs/Getting Started/AI-Packages.md b/docs/Getting Started/AI-Packages.md new file mode 100644 index 0000000..df49f27 --- /dev/null +++ b/docs/Getting Started/AI-Packages.md @@ -0,0 +1,149 @@ +# AI Package Deep Dive + +Dit document beschrijft de `smart_gestures`-package die de Signapse AI-modellen bundelt. De focus ligt op module-indeling, gebruikte PyTorch-componenten, inference-preprocessing en trainingsutilities rond MediaPipe en NumPy. + +## Package-overzicht + +`smart_gestures` wordt vanuit `notebooks/package/` gebouwd en als PyPI-package gedeeld. De submodules zijn strikt gescheiden per taak zodat modellen onafhankelijk kunnen worden geüpdatet. + +```text +smart_gestures/ +├── __init__.py +├── alphabet/ +│ ├── __init__.py +│ ├── asl_model/ +│ │ ├── model.py # ASLModel + normalize_landmarks +│ │ ├── data/classes.json # label mapping +│ │ └── models/*.pth # getrainde weights +│ └── vgt_model/ +│ ├── model.py +│ ├── data/classes.json +│ └── models/*.pth +└── gestures/ + └── lstm_model/ + ├── model.py # LSTMModel + sequence normalisatie + ├── data/gesture_map.json + └── models/lstm_model.pth +``` + +### Modelbestanden & laden + +- Elke submodule bewaart `.pth`-bestanden onder `models/`. De bestanden bevatten het `state_dict` van de PyTorch-module. +- De corresponderende `model.py` laadt de klassen (`classes.json` of `gesture_map.json`), instantiëert de architectuur en roept `torch.load(..., map_location=DEVICE)` om de gewichten in te lezen. +- Tijdens instantiatie wordt het model direct in `eval()`-modus gezet zodat inference consistent blijft (`ASLModel` en `VGTModel` in hun `__init__`, `LSTMModel` idem). + +## PyTorch-componenten + +| Component | Gebruikt in | Functie | Motivatie | +|-----------|-------------|---------|-----------| +| `nn.Sequential` | Alphabet-modellen (`asl_model/model.py`, `vgt_model/model.py`) | Lineaire feed-forward stack | Eenvoudig te lezen/aanpassen; ideaal voor statische 63-d input. | +| `nn.Linear` | Alle modellen | Projecteert features naar volgende laag of klassenruimte | Volledige connectiviteit nodig omdat keypoints al dense zijn. | +| `nn.ReLU` | Alphabet-netwerken | Niet-lineariteit | Houdt training stabiel zonder extra parameters. | +| `nn.Dropout(0.2)` | Alphabet- en LSTM-outputlaag | Regularisatie | Vermindert overfitting bij beperkte datasets zonder inference-penalty. | +| `nn.LSTM` | `gestures/lstm_model/model.py` | Tijdelijke verwerking van 40×258 sequenties | Bewaart temporele context van pose + beide handen. | +| `torch.nn.utils.rnn.pack_padded_sequence` + `pad_packed_sequence` | `LSTMModel.forward` | Efficiënte verwerking van ge-padding sequenties | Bespaart rekenkracht doordat daadwerkelijke lengtes worden gebruikt. | +| `torch.softmax` | Alle `predict()`-methodes | Confidence berekening | Nodig voor REST-responses en loss-functies (Brier-penalty). | +| `torch.load` / `state_dict` | Alle `model.py` | Modelgewichten laden | Houdt package-artefacten klein en compatibel met PyTorch tooling. | + +## Inference-paden + +### Alphabet-modellen (ASL/VGT) +1. **Data-ingang**: lijst van 21 landmarks met `x,y,z`-velden (MediaPipe Hands output). +2. **Normalisatie** (`normalize_landmarks`): translatie naar pols-oorsprong + schaling op `wrist_to_middle` afstand; resulteert in een `(21, 3)` array. +3. **Flattening**: `reshape(-1)` → 63 features. +4. **Tensor-voorbereiding**: `torch.from_numpy(...).reshape(1, IN_DIM)` op CPU of CUDA device. +5. **Forward pass**: `nn.Sequential` produceert logits, daarna softmax voor klasse + confidence. + +### LSTM woordmodel +1. **Data-ingang**: sequentie van maximaal 40 frames waarin elk frame 258 features heeft (`pose + left hand + right hand`). Deze 258-d vectoren worden opgebouwd door de MediaPipe `/keypoints/pose` endpoint. +2. **Normalisatie** (`normalize_landmarks` in `gestures/lstm_model/model.py`): centreert hand-keypoints op het eerst gedetecteerde polskoordinaat en schaalt op de pols → middelvinger afstand. Pose-coördinaten blijven ongewijzigd. +3. **Padding/Truncation** (`prepare_input`): sequenties korter dan 40 frames worden met nullen opgevuld; langere sequenties worden afgekapt. De bijhorende lengte wordt meegegeven voor packed sequences. +4. **LSTM forward**: `pack_padded_sequence` zorgt dat alleen echte frames door de `nn.LSTM` gaan. De laatste time-step output passeert door dropout + `nn.Linear`. +5. **Softmax** geeft de vijf woordklassen (`gesture_map.json`) met confidence terug. + +## Training utilities + +| Module | Pad | Rol | +|--------|-----|-----| +| `data_utils.py` | `notebooks/training/*/data_utils.py` | Normaliseert landmerken, voorziet PyTorch `Dataset`/`DataLoader`, en ondersteunt augmentaties zoals rotatie en Gaussian noise (belangrijk om MediaPipe-variaties te simuleren). | +| `train_utils.py` | `notebooks/training/*/train_utils.py` | Train-loop met mixup, label smoothing, Brier-regularisatie, misclassificatie-penalty, scheduler/early-stop hooks. Verbindt NumPy batches met PyTorch-modellen. | +| `callbacks.py` | `notebooks/training/vgt_model/callbacks.py` (gedeeld) | `EarlyStopping`, `ModelCheckpoint` en `create_scheduler` wrappers voor ReduceLROnPlateau/Step/Cosine. | +| `model_utils.py` | `notebooks/training/*/model_utils.py` | Bouwt dezelfde architecturen die later in `smart_gestures` terechtkomen. | +| `run_training.py` | `notebooks/training/*/run_training.py` | CLI-entrypoint dat hyperparameters en augmentatie/scheduler-opties bundelt. | + +De utilities combineren PyTorch met MediaPipe-output door datasets eerst via `normalize_landmarks` te aligneren. Augmentaties zoals rotatie/noise en mixup zorgen dat modellen robuust blijven voor variaties in MediaPipe-detecties op verschillende devices. NumPy wordt gebruikt voor bulkmanipulaties, waarna `torch.from_numpy` tensors genereert voor training en inference. + +## Model lifecycle + +Onderstaande checklist beschrijft hoe een nieuw `.pth`-model in productie komt: + +1. **Train** – gebruik de relevante `notebooks/training/*/run_training.py` of Jupyter-notebook en leg hyperparameters vast (zie tabel hieronder). +2. **Valideer** – evalueer met `evaluate_model`/`evaluate_metrics` en archiveer accuracy-, loss- en calibratiecijfers. +3. **Promoot gewichten** – kopieer het beste `.pth` naar de juiste `notebooks/package/smart_gestures/.../models/` map en commit/bewaar de bijhorende `classes.json`/`gesture_map.json` updates. +4. **Bump package** – verhoog `version` in `notebooks/package/pyproject.toml`, voer `python -m build` uit en publiceer/installeer de nieuwe `smart_gestures` release (lokaal kan `pip install -e .` volstaan). +5. **Update server** – pas `server/pyproject.toml` en `server/requirements.txt` aan naar de nieuwe `smart-gestures` versie zodat FastAPI het juiste artefact laadt. +6. **Regressietests** – draai minimaal de API smoke-tests (ASL/VGT/LSTM inferentie tegen bekende voorbeelden) voordat er gedeployed wordt. + +## CLI-argumenten per trainingsscript + +### ASL alphabet (`notebooks/training/asl_model/run_training.py`) + +| Argument | Default | Omschrijving | +|----------|---------|--------------| +| `--batch_size` | 32 | Batchgrootte voor DataLoader. | +| `--epochs` | 20 | Aantal volledige epochs. | +| `--lr` | 1e-3 | Learning rate voor Adam-optimizer. | +| `--output` | `asl_alphabet_model.pth` | Doelpad voor het opgeslagen model (wordt later naar `smart_gestures` gekopieerd). | + +### VGT alphabet (`notebooks/training/vgt_model/run_training.py`) + +| Argument | Default | Omschrijving | +|----------|---------|--------------| +| `--batch_size` | 32 | Batchgrootte voor trainingen/validatie. | +| `--epochs` | 50 | Maximale epochs (early stop kan eerder afbreken). | +| `--lr` | 1e-3 | Learning rate voor Adam. | +| `--output` | `vgt_alphabet_model.pth` | Bestandsnaam voor de finale `.pth`. | +| `--augment` | `False` (flag) | Activeer data-augmentatie in `LandmarksDataset`. | +| `--augment_prob` | 0.5 | Kans dat augmentaties worden toegepast per sample. | +| `--noise_std` | 0.01 | Std-dev van Gaussian noise tijdens augmentatie. | +| `--rotate_deg` | 10.0 | Maximale random rotatie in graden. | +| `--scheduler` | `plateau` | Scheduler-type: `none`, `plateau`, `step`, `cosine`. | +| `--scheduler_factor` | 0.5 | Factor voor `ReduceLROnPlateau`. | +| `--scheduler_patience` | 3 | Patience voor `ReduceLROnPlateau`. | +| `--step_size` | 10 | Stapgrootte indien `scheduler=step`. | +| `--gamma` | 0.1 | Decayfactor voor StepLR. | +| `--early_stop_patience` | 5 | #epochs zonder verbetering voordat training stopt. | +| `--early_stop_min_delta` | 0.0 | Minimale verbetering om early stop te resetten. | +| `--monitor` | `val_loss` | Metric voor early stop/checkpoint (`val_loss` of `val_acc`). | +| `--checkpoint` | `False` (flag) | Schakel model-checkpointing in. | +| `--checkpoint_path` | `best_vgt_model.ckpt` | Pad/naam voor checkpoints. | +| `--label_smoothing` | 0.1 | Factor voor CrossEntropy label smoothing. | +| `--lambda_brier` | 1.1 | Weights voor Brier-score regularisatie. | +| `--misclass_alpha` | 0.1 | gewicht voor misclassificatie-confidence penalty. | +| `--mixup_alpha` | 0.2 | Mixup Beta-parameter (0 schakelt mixup uit). | + +### LSTM gestures (`notebooks/training/lstm_model/run_training.py`) + +| Argument | Default | Omschrijving | +|----------|---------|--------------| +| `--batch_size` | 32 | Batchgrootte voor sequenties. | +| `--epochs` | 50 | Aantal epochs voor sequentietraining. | +| `--lr` | 1e-3 | Learning rate. | +| `--hidden_size` | 128 | Verborgen dimensie van de LSTM-layer(s). | +| `--num_layers` | 2 | Aantal gestapelde LSTM-lagen. | +| `--output` | `lstm_model.pth` | Bestandsnaam voor het opgeslagen woordmodel. | + +## Relevante bronnen & links + +- `notebooks/package/smart_gestures/alphabet/asl_model/model.py` — inference-logica en `nn.Sequential` opbouw voor ASL. +- `notebooks/package/smart_gestures/alphabet/vgt_model/model.py` — identieke architectuur met aangepaste label-set en calibratie callbacks. +- `notebooks/package/smart_gestures/gestures/lstm_model/model.py` — sequentiële preprocess, `nn.LSTM` en padded sequence handling. +- `notebooks/training/asl_model/run_training.py`, `.../vgt_model/run_training.py`, `.../lstm_model/run_training.py` — beschrijven hoe datasets geladen en modellen getraind worden met augmentaties, callbacks en checkpoints. +- `docs/Architecture/README.md` — high-level architectuur; combineer dit document voor deep-dive info met het hoofdarchitectuuroverzicht. + +**Document-informatie**: + +- **Versie**: 1.0 +- **Datum**: December 2025 +- **Auteurs**: Lynn Delaere +- **Contact**: Zie [GitHub repository](https://github.com/vives-project-xp/Signapse) diff --git a/docs/Getting Started/Development/Model-Retrain.md b/docs/Getting Started/Development/Model-Retrain.md new file mode 100644 index 0000000..78b9376 --- /dev/null +++ b/docs/Getting Started/Development/Model-Retrain.md @@ -0,0 +1,191 @@ +# Model Retraining & LakeFS Workflow + +Deze README begeleidt nieuwe teamleden die **nieuwe data** willen toevoegen en een `smart_gestures`-model opnieuw moeten trainen. We behandelen eerst het **VGT-alfabetmodel** en vervolgens het **LSTM-woordmodel**. + +## Overzicht Stappen + +1. Verzamel/normaliseer je data (bijv. `webcam_landmarks.py` voor alfabetten, `capture_dataset_lstm.py` voor sequenties). +2. Check een LakeFS-branch uit, voeg de ruwe en verwerkte data toe en commit/push. +3. Download de data via `lakectl local clone` of `lakectl local pull` en wijs de trainingsscripts naar die map (`LAKEFS_DATA_PATH`). +4. Train, valideer en sla het `.pth`-bestand op. +5. Kopieer het model naar `notebooks/package/smart_gestures/.../models/`, bump `smart_gestures` en update de FastAPI- afhankelijkheid (zie [AI-Packages.md](./AI-Packages.md#model-lifecycle)). + +## 1. Voorwaarden + +- LakeFS + Minio draaien lokaal en CLI-tools zijn geconfigureerd. Volg [setup_guide_lakefs_minio.md](../Getting%20Started/Development/setup_guide_lakefs_minio.md) om: + - `docker compose up -d` te draaien in `notebooks/`. + - `lakectl`/`mc` te installeren en `lakectl config` uit te voeren. +- Virtuele omgeving met de notebook-dependencies (bijv. `python3.12 -m venv .venv && source .venv/bin/activate && pip install -r notebooks/requirements.txt`). + +## 2. VGT-alfabet opnieuw trainen + +### 2.1 Data verzamelen (VGT) + +1. Gebruik één van de utilities in `notebooks/utilities/`: + - `webcam_landmarks.py` / `static_image_landmarks.py` voor snelle opnames. + - `extract_landmarks_from_dataset.py` of `csv_to_json.py` om bestaande datasets om te zetten. +2. Bewaar de labels exact zoals in `smart_gestures/alphabet/vgt_model/data/classes.json` (A-Z). Elk record in de JSONL/CSV bevat 21 landmarks (x,y,z). +3. Voeg context toe (datum, gebaarder, camerapositie) in een `README-data.md` zodat reviewers weten waar de samples vandaan komen. + +### 2.2 Data naar LakeFS pushen (VGT) + +Gebruik hetzelfde LakeFS-proces voor elke dataset: + +```bash +# Maak branch +lakectl branch create lakefs://signapse-data/feature/new-vgt-data \ + --source lakefs://signapse-data/main + +# Clone lokaal +lakectl local clone lakefs://signapse-data/feature/new-vgt-data data-lake +cd data-lake +``` + +Kopieer je nieuwe alfabetdataset naar `datasets/vgt//hand_landmarks.json` (of .csv) en voer `lakectl local commit` + `lakectl local push` uit. + +### 2.3 Data gebruiken in notebooks (VGT) + +1. Op de trainingsmachine: + + ```bash + lakectl local pull data-lake + export LAKEFS_DATA_PATH=/pad/naar/data-lake/datasets/vgt/2024-12 + ``` + +2. Kopieer of symlink het bestand naar `notebooks/training/vgt_model/data/hand_landmarks.json` (of update de scripts om rechtstreeks naar `LAKEFS_DATA_PATH` te wijzen). + +### 2.4 VGT-model trainen + +1. Activeer de venv en ga naar de trainingsmap: + + ```bash + cd notebooks + pip install -r requirements.txt + cd training/vgt_model + ``` + +2. Start de training met de gewenste hyperparameters (zie [CLI-tabel](./AI-Packages.md#cli-argumenten-per-trainingsscript)): + + ```bash + python run_training.py \ + --batch_size 64 \ + --epochs 60 \ + --lr 5e-4 \ + --augment \ + --augment_prob 0.6 \ + --noise_std 0.02 \ + --rotate_deg 15 \ + --scheduler plateau \ + --label_smoothing 0.1 \ + --lambda_brier 1.0 \ + --output vgt_alphabet_model_2024_12.pth + ``` + +3. Controleer accuracy/loss en noteer belangrijke metrics (bijv. calibratie resultaten). + +### 2.5 Valideren & promoten (VGT) + +1. Kopieer het model naar het package: + + ```bash + cp vgt_alphabet_model_2024_12.pth ../../package/smart_gestures/alphabet/vgt_model/models/vgt_alphabet_model.pth + ``` + +2. Update `classes.json` indien de labelset uitbreidt. +3. Volg de [model lifecycle](./AI-Packages.md#model-lifecycle) voor package bump, dependency-updates en smoke-tests (focus op `/alphabet/vgt/predict`). + +## 3. LSTM-woordmodel opnieuw trainen + +### 3.1 Nieuwe data verzamelen (LSTM) + +1. Gebruik `notebooks/utilities/capture_dataset_lstm.py` om keypoint-sequenties op te nemen. Het script creëert een mapstructuur van de vorm: + + ``` + dataset/ + ├── hallo/ + │ └── 000/ + │ └── 2024-12-11T10-00-00/ + │ ├── keypoints_000.npy + │ ├── keypoints_001.npy + │ └── ... + ``` + +2. Controleer of elk gebaar minstens `SEQUENCE_LENGTH` (40) frames bevat. Bij minder frames vult het trainingsscript wel aan, maar variatie per gebaar is gewenst. +3. Documenteer meta-informatie (datum, performer, omgeving) zodat reviewers weten waar de data vandaan komt. Bewaar deze info in een `README-data.md` in dezelfde map. + +### 3.2 Data naar LakeFS pushen (LSTM) + +Volg dezelfde werkwijze als voor VGT, maar groepeer je data onder `datasets/lstm//`. Gebruik een specifieke branchnaam, bijvoorbeeld `feature/new-lstm-data`, en commit/push via `lakectl local commit`. + +### 3.3 Data downloaden/verwijzen in notebooks + +1. Clone/pull de branch op de machine waar je gaat trainen (`lakectl local clone ...` of `lakectl local pull`). +2. Wijs het trainingsscript naar de LakeFS-checkout door de env var `LAKEFS_DATA_PATH` te zetten: + + ```bash + export LAKEFS_DATA_PATH=/pad/naar/data-lake/datasets/lstm/2024-12-new-recordings + ``` + + De LSTM `data_utils.py` haalt automatisch dit pad op. Zonder env var gebruikt het script de lokale `notebooks/training/lstm_model/dataset` map. + +### 3.4 LSTM-model trainen + +1. Activeer je virtuele omgeving en installeer dependencies: + + ```bash + cd notebooks + pip install -r requirements.txt + ``` + +2. Start training vanuit `notebooks/training/lstm_model/`: + + ```bash + cd notebooks/training/lstm_model + python run_training.py \ + --batch_size 32 \ + --epochs 60 \ + --lr 5e-4 \ + --hidden_size 128 \ + --num_layers 2 \ + --output lstm_model_2024_12.pth + ``` + + Pas de argumenten aan op basis van [de CLI-tabel](./AI-Packages.md#cli-argumenten-per-trainingsscript). + +3. Controleer de console-output en noteer de validatie-accuracy. + +### 3.5 Valideren & promoten (LSTM) + +1. Gebruik `evaluate_model` of schrijf een extra notebook/testscript dat inference doet op bekende sequences. +2. Kopieer het beste `.pth` bestand naar het package: + + ```bash + cp lstm_model_2024_12.pth ../../package/smart_gestures/gestures/lstm_model/models/lstm_model.pth + ``` + +3. Update eventueel `gesture_map.json` en commit de wijzigingen. +4. Volg de [model lifecycle checklist](./AI-Packages.md#model-lifecycle): + - Bump `smart_gestures` versie in `notebooks/package/pyproject.toml`. + - Bouw/publiceer of installeer het nieuwe package (bijv. `pip install -e notebooks/package`). + - Update `server/pyproject.toml` en `server/requirements.txt` zodat de FastAPI backend het nieuwe package gebruikt. + - Draai smoke-tests (`/alphabet/asl/predict`, `/alphabet/vgt/predict`, `/gestures/lstm/predict`) en commit de code. + +## 4. LakeFS housekeeping + +1. Voeg je nieuwe `.pth` en alle dataset changes toe aan dezelfde LakeFS-branch (zowel ruwe als verwerkte bestanden). +2. Commit en maak een merge request richting `main`. Gebruik de LakeFS UI om diffs te keuren en een reviewer te taggen. +3. Na merge kun je de lokale checkout updaten en de branch opruimen: + + ```bash + lakectl local pull data-lake + lakectl branch delete lakefs://signapse-data/feature/new-data + ``` + +Nu is de dataset geversioneerd, het model opnieuw getraind en het backend package bijgewerkt. Nieuwe teamleden kunnen deze README volgen voor alle toekomstige retrainings. + +**Document-informatie**: + +- **Versie**: 1.0 +- **Datum**: December 2025 +- **Auteurs**: Lynn Delaere +- **Contact**: Zie [GitHub repository](https://github.com/vives-project-xp/Signapse)