islkit 0.1.0__tar.gz

islkit-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+# Figures and summaries under runs/ are committed; weights and logs are not.
+*.log
+data/
+*.pt
+*.onnx
+.DS_Store

islkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jayraj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

islkit-0.1.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.5
+Name: islkit
+Version: 0.1.0
+Summary: Indian Sign Language recognition from MediaPipe landmarks: features, a dual-branch TCN, and a live recognition service
+Project-URL: Homepage, https://github.com/jbrathwa/islkit
+Project-URL: Issues, https://github.com/jbrathwa/islkit/issues
+Author: Jayraj
+License-Expression: MIT
+License-File: LICENSE
+Keywords: accessibility,isl,landmarks,mediapipe,sign-language,tcn
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: <3.13,>=3.12
+Requires-Dist: mediapipe==0.10.18
+Requires-Dist: numpy<2,>=1.26
+Requires-Dist: torch>=2.5
+Provides-Extra: train
+Requires-Dist: pandas>=3.0.5; extra == 'train'
+Requires-Dist: pyarrow>=25.0.1; extra == 'train'
+Requires-Dist: xgboost>=3.4.1; extra == 'train'
+Description-Content-Type: text/markdown
+
+# islkit
+
+Indian Sign Language (ISL) recognition from MediaPipe Holistic landmarks.
+
+islkit turns camera frames into glosses. It covers every step: a landmark
+feature encoder, a dual-branch temporal convolutional network (TCN), a loader
+for the INCLUDE dataset, live inference with a confidence-gated decline, and a
+small HTTP/SSE recognition service. It runs on CPU and is built to work on small
+ARM boards as well as laptops.
+
+```
+camera → MediaPipe Holistic → RawFrame → encode_clip (T×352) → TCN → gloss | None
+```
+
+## Install
+
+```sh
+pip install islkit            # inference and the recognition service
+pip install "islkit[train]"   # + pandas, pyarrow, xgboost for INCLUDE and the baseline
+```
+
+Requires **Python 3.12**. `mediapipe` is pinned to `0.10.18`, which also pins
+`numpy<2`. That is the last MediaPipe release that keeps `mp.solutions` and
+still runs on ARMv8.0-A (Cortex-A53) boards.
+
+On macOS, XGBoost needs `brew install libomp`. Don't import `torch` and
+`xgboost` in the same process: each bundles its own libomp, and the process
+aborts with `OMP: Error #15`. `import islkit` keeps torch lazy for this reason.
+
+## Design
+
+**Features, not raw landmarks.** Holistic's flattened output has 1,662 values,
+and 85% of them are face mesh. The encoder reduces each frame to **183 floats**
+(352 with velocity):
+
+| Block                          | Dims |
+|--------------------------------|------|
+| Hand-local shapes (2 × 21 × 3) | 126  |
+| Wrist positions in body frame  | 6    |
+| Upper-body pose (11 landmarks) | 33   |
+| Non-manual scalars from face   | 4    |
+| Validity mask                  | 14   |
+
+The encoder uses three coordinate frames rather than one normalisation. Body
+frame: origin at the shoulder midpoint, scaled by shoulder width. Hand-local
+frame: origin at the wrist, scaled by the wrist-to-middle-MCP distance. Wrist
+position is recovered separately in the body frame. This keeps handshape
+separate from location.
+
+**Principles the code enforces:**
+
+- **Hand slots are geometric.** Slot 0 is the hand nearer the dominant-side
+  shoulder. MediaPipe's handedness label flips under occlusion and is never read.
+- **Mask, never zero-fill.** A missing hand is not a hand at the origin. A
+  validity bit is carried per part and multiplied through the network.
+- **The label map is frozen.** `LabelMap` is saved beside the weights. Class
+  order rebuilt from a directory listing silently shifts indices.
+- **Checkpoints are tied to the encoder.** A checkpoint records an encoder
+  fingerprint, and `SignRecogniser` refuses to serve it through a different
+  encoder.
+- **Store raw landmarks.** Recordings hold raw MediaPipe output, so they can
+  be re-encoded when the normalisation changes.
+- **The model can say "I don't know".** Below the confidence threshold a
+  prediction is `None`. For an accessibility device, silence is better than a
+  confident wrong answer.
+
+## Usage
+
+### Encode a clip
+
+```python
+from islkit import encode_clip
+from islkit.infer import HolisticExtractor
+
+frames = []
+with HolisticExtractor() as extractor:
+    for frame_bgr in video_frames:          # BGR numpy arrays, e.g. from cv2
+        _, raw, _ = extractor.process(frame_bgr)
+        frames.append(raw)
+
+clip = encode_clip(frames, T=48)            # (48, 352) float32
+```
+
+### Recognise a sign
+
+```python
+from islkit import SignRecogniser
+
+recogniser = SignRecogniser("classifier.pt", threshold=0.6)  # labels_*.json beside it
+prediction = recogniser.classify(frames)
+print(prediction.gloss, prediction.confidence, prediction.top3)
+```
+
+`prediction.gloss` is `None` when the model declines.
+
+### Train
+
+```python
+from islkit import build_model, load_include
+from islkit.model import fit
+
+data = load_include("path/to/isl-mediapipe-holistic-landmarks")   # data.X: (N, 48, 352)
+model = build_model(n_classes=len(data.label_map))
+fit(model, data.X, data.y)
+```
+
+`load_include` reads the Kaggle
+[`indian-sign-language-mediapipe-holistic-landmarks`](https://www.kaggle.com/datasets/swaptr/indian-sign-language-mediapipe-holistic-landmarks)
+dump of INCLUDE and caches the encoded arrays. That dump records no signer or
+session, so a class-stratified k-fold over whole clips is the only honest split
+available. It still leaks signers, so **report numbers from it as optimistic**.
+For your own recordings, use leave-one-session-out: `build_dataset` returns a
+`sessions` array for this.
+
+`replace_head` and `freeze_backbone` support fine-tuning a pretrained backbone
+on a smaller vocabulary. Always report per-class F1 (`per_class_f1`), not just
+aggregate accuracy.
+
+### Run the recognition service
+
+```python
+import threading
+from islkit.infer import ClipStore, HolisticExtractor, SignRecogniser
+from islkit.pipeline import CameraSource, RecognitionPipeline
+from islkit.server import EventHub, make_server
+
+recogniser = SignRecogniser("classifier.pt")
+hub = EventHub()
+pipeline = RecognitionPipeline(
+    recogniser=recogniser,
+    source_factory=lambda: CameraSource(0, "1280x720"),
+    on_event=hub.publish,
+    extractor_factory=HolisticExtractor,
+    store=ClipStore(),
+    on_pause=hub.clear_take,
+)
+threading.Thread(target=pipeline.run, daemon=True).start()
+make_server(pipeline, hub).serve_forever()     # 127.0.0.1:9978
+```
+
+| Route           | Does                                   |
+|-----------------|----------------------------------------|
+| `GET /results`  | Server-sent events: tracking, takes, predictions |
+| `POST /capture` | Start or pause capture                 |
+| `GET /health`   | Pipeline and subscriber status         |
+
+`islkit.view.make_view_server` serves an optional annotated MJPEG debug view
+on a separate port.
+
+Pretrained weights are not shipped with the package.
+
+## Guides and experiments
+
+- [`docs/`](docs/README.md): how the features, dataset, baseline, pretraining and fine-tuning
+  work, each argued from committed results.
+- [`experiments/`](experiments/README.md): the scripts that produce those results, runnable from
+  a clone of this repository.
+
+## Development
+
+```sh
+uv sync --extra train
+uv run pytest
+uv run ruff check .
+```
+
+The tests cover the properties that would silently break recognition: encoder
+invariances, mask gating, label-map and checkpoint round-trips, and the
+saved-clip layout.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

islkit-0.1.0/README.md

@@ -0,0 +1,173 @@
+# islkit
+
+Indian Sign Language (ISL) recognition from MediaPipe Holistic landmarks.
+
+islkit turns camera frames into glosses. It covers every step: a landmark
+feature encoder, a dual-branch temporal convolutional network (TCN), a loader
+for the INCLUDE dataset, live inference with a confidence-gated decline, and a
+small HTTP/SSE recognition service. It runs on CPU and is built to work on small
+ARM boards as well as laptops.
+
+```
+camera → MediaPipe Holistic → RawFrame → encode_clip (T×352) → TCN → gloss | None
+```
+
+## Install
+
+```sh
+pip install islkit            # inference and the recognition service
+pip install "islkit[train]"   # + pandas, pyarrow, xgboost for INCLUDE and the baseline
+```
+
+Requires **Python 3.12**. `mediapipe` is pinned to `0.10.18`, which also pins
+`numpy<2`. That is the last MediaPipe release that keeps `mp.solutions` and
+still runs on ARMv8.0-A (Cortex-A53) boards.
+
+On macOS, XGBoost needs `brew install libomp`. Don't import `torch` and
+`xgboost` in the same process: each bundles its own libomp, and the process
+aborts with `OMP: Error #15`. `import islkit` keeps torch lazy for this reason.
+
+## Design
+
+**Features, not raw landmarks.** Holistic's flattened output has 1,662 values,
+and 85% of them are face mesh. The encoder reduces each frame to **183 floats**
+(352 with velocity):
+
+| Block                          | Dims |
+|--------------------------------|------|
+| Hand-local shapes (2 × 21 × 3) | 126  |
+| Wrist positions in body frame  | 6    |
+| Upper-body pose (11 landmarks) | 33   |
+| Non-manual scalars from face   | 4    |
+| Validity mask                  | 14   |
+
+The encoder uses three coordinate frames rather than one normalisation. Body
+frame: origin at the shoulder midpoint, scaled by shoulder width. Hand-local
+frame: origin at the wrist, scaled by the wrist-to-middle-MCP distance. Wrist
+position is recovered separately in the body frame. This keeps handshape
+separate from location.
+
+**Principles the code enforces:**
+
+- **Hand slots are geometric.** Slot 0 is the hand nearer the dominant-side
+  shoulder. MediaPipe's handedness label flips under occlusion and is never read.
+- **Mask, never zero-fill.** A missing hand is not a hand at the origin. A
+  validity bit is carried per part and multiplied through the network.
+- **The label map is frozen.** `LabelMap` is saved beside the weights. Class
+  order rebuilt from a directory listing silently shifts indices.
+- **Checkpoints are tied to the encoder.** A checkpoint records an encoder
+  fingerprint, and `SignRecogniser` refuses to serve it through a different
+  encoder.
+- **Store raw landmarks.** Recordings hold raw MediaPipe output, so they can
+  be re-encoded when the normalisation changes.
+- **The model can say "I don't know".** Below the confidence threshold a
+  prediction is `None`. For an accessibility device, silence is better than a
+  confident wrong answer.
+
+## Usage
+
+### Encode a clip
+
+```python
+from islkit import encode_clip
+from islkit.infer import HolisticExtractor
+
+frames = []
+with HolisticExtractor() as extractor:
+    for frame_bgr in video_frames:          # BGR numpy arrays, e.g. from cv2
+        _, raw, _ = extractor.process(frame_bgr)
+        frames.append(raw)
+
+clip = encode_clip(frames, T=48)            # (48, 352) float32
+```
+
+### Recognise a sign
+
+```python
+from islkit import SignRecogniser
+
+recogniser = SignRecogniser("classifier.pt", threshold=0.6)  # labels_*.json beside it
+prediction = recogniser.classify(frames)
+print(prediction.gloss, prediction.confidence, prediction.top3)
+```
+
+`prediction.gloss` is `None` when the model declines.
+
+### Train
+
+```python
+from islkit import build_model, load_include
+from islkit.model import fit
+
+data = load_include("path/to/isl-mediapipe-holistic-landmarks")   # data.X: (N, 48, 352)
+model = build_model(n_classes=len(data.label_map))
+fit(model, data.X, data.y)
+```
+
+`load_include` reads the Kaggle
+[`indian-sign-language-mediapipe-holistic-landmarks`](https://www.kaggle.com/datasets/swaptr/indian-sign-language-mediapipe-holistic-landmarks)
+dump of INCLUDE and caches the encoded arrays. That dump records no signer or
+session, so a class-stratified k-fold over whole clips is the only honest split
+available. It still leaks signers, so **report numbers from it as optimistic**.
+For your own recordings, use leave-one-session-out: `build_dataset` returns a
+`sessions` array for this.
+
+`replace_head` and `freeze_backbone` support fine-tuning a pretrained backbone
+on a smaller vocabulary. Always report per-class F1 (`per_class_f1`), not just
+aggregate accuracy.
+
+### Run the recognition service
+
+```python
+import threading
+from islkit.infer import ClipStore, HolisticExtractor, SignRecogniser
+from islkit.pipeline import CameraSource, RecognitionPipeline
+from islkit.server import EventHub, make_server
+
+recogniser = SignRecogniser("classifier.pt")
+hub = EventHub()
+pipeline = RecognitionPipeline(
+    recogniser=recogniser,
+    source_factory=lambda: CameraSource(0, "1280x720"),
+    on_event=hub.publish,
+    extractor_factory=HolisticExtractor,
+    store=ClipStore(),
+    on_pause=hub.clear_take,
+)
+threading.Thread(target=pipeline.run, daemon=True).start()
+make_server(pipeline, hub).serve_forever()     # 127.0.0.1:9978
+```
+
+| Route           | Does                                   |
+|-----------------|----------------------------------------|
+| `GET /results`  | Server-sent events: tracking, takes, predictions |
+| `POST /capture` | Start or pause capture                 |
+| `GET /health`   | Pipeline and subscriber status         |
+
+`islkit.view.make_view_server` serves an optional annotated MJPEG debug view
+on a separate port.
+
+Pretrained weights are not shipped with the package.
+
+## Guides and experiments
+
+- [`docs/`](docs/README.md): how the features, dataset, baseline, pretraining and fine-tuning
+  work, each argued from committed results.
+- [`experiments/`](experiments/README.md): the scripts that produce those results, runnable from
+  a clone of this repository.
+
+## Development
+
+```sh
+uv sync --extra train
+uv run pytest
+uv run ruff check .
+```
+
+The tests cover the properties that would silently break recognition: encoder
+invariances, mask gating, label-map and checkpoint round-trips, and the
+saved-clip layout.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

islkit-0.1.0/docs/README.md

@@ -0,0 +1,21 @@
+# islkit guides
+
+Each guide explains one part of the pipeline and argues from results committed under
+[`runs/`](../runs), produced by the scripts in [`experiments/`](../experiments). Every number can be
+regenerated with the command next to it.
+
+| Guide | Covers |
+|---|---|
+| [Landmark features](features.md) | The 183-dim encoder, its invariances, and the replay instrument that checks them by eye |
+| [The INCLUDE dataset](include-dataset.md) | Layout, the missing signer identifier, tracking quality, and the replay on real landmarks |
+| [Baseline](baseline.md) | Pooled statistics + XGBoost: the floor a sequence model has to clear |
+| [Pretraining](pretraining.md) | The dual-branch TCN on INCLUDE, its controls, and why its accuracy is not a device accuracy |
+| [Fine-tuning](fine-tuning.md) | Choosing a vocabulary, two-stage fine-tuning on your own recordings, and training for a device camera |
+
+## One caveat that applies everywhere
+
+The public INCLUDE landmark dump does not record who signed each clip, so no split can hold out
+signers. Every INCLUDE number in these guides comes from a class-stratified k-fold over whole clips,
+which is **optimistic**: the same signers appear on both sides of every fold. They show that the
+features and models work; they do not estimate accuracy for a new signer. See
+[the dataset guide](include-dataset.md#2-there-is-no-signer-identifier).

islkit-0.1.0/experiments/README.md

@@ -0,0 +1,55 @@
+# Experiments
+
+Runnable scripts that exercise `islkit` end to end. Each one writes to `runs/<experiment>/`, and
+the guides in [`docs/`](../docs) argue from those outputs. Figures and summaries are committed;
+weights (`*.pt`, `*.onnx`) and logs are not.
+
+## Setup
+
+```sh
+uv sync --extra train                      # pandas, pyarrow and xgboost for the INCLUDE experiments
+export ISLKIT_INCLUDE_ROOT=/path/to/isl-mediapipe-holistic-landmarks
+```
+
+Run every script from the repository root, so `runs/` and the `data/cache/` of encoded INCLUDE
+clips land in the right place. The INCLUDE dump is the Kaggle dataset
+[`swaptr/indian-sign-language-mediapipe-holistic-landmarks`](https://www.kaggle.com/datasets/swaptr/indian-sign-language-mediapipe-holistic-landmarks)
+(3.4 GB). The first script that loads it encodes all 4,284 clips into a 291 MB cache.
+
+On macOS, XGBoost needs `brew install libomp`. torch and XGBoost each bundle their own OpenMP
+runtime and abort when loaded into one process, which is why the baseline and the TCN are separate
+scripts.
+
+## The scripts
+
+| Script | Needs | Writes | Guide |
+|---|---|---|---|
+| `feature_smoke.py` | nothing | stdout only | [features](../docs/features.md#4-cost) |
+| `replay_features.py` | nothing | `runs/replay_features/` | [features](../docs/features.md#5-seeing-the-features-the-replay-instrument) |
+| `tcn_gestures.py` | nothing | `runs/tcn_gestures/` | below |
+| `inspect_include.py` | INCLUDE | `runs/inspect_include/` | [INCLUDE](../docs/include-dataset.md) |
+| `replay_include.py` | INCLUDE | `runs/replay_include/` | [INCLUDE](../docs/include-dataset.md#4-the-replay-on-real-landmarks) |
+| `baseline_xgb.py` | INCLUDE | `runs/baseline_xgb/` | [baseline](../docs/baseline.md) |
+| `pretrain.py` | INCLUDE, baseline summary | `runs/pretrain/` | [pretraining](../docs/pretraining.md) |
+| `vocab_confusability.py` | INCLUDE | `data/vocab.json` | [fine-tuning](../docs/fine-tuning.md#2-choose-the-vocabulary-before-recording-it) |
+| `finetune.py` | INCLUDE, own recordings, pretrained classifier | `runs/finetune/` | [fine-tuning](../docs/fine-tuning.md#4-two-stage-fine-tuning) |
+| `device_head.py` | INCLUDE, pretrained backbone, a vocabulary | `runs/device_head/` | [fine-tuning](../docs/fine-tuning.md#5-training-for-the-devices-camera) |
+
+Each script's docstring lists its flags; `--help` prints them. `pretrain.py`, `finetune.py` and
+`device_head.py` take `--smoke` for a fast wiring check.
+
+Run them in table order the first time: `pretrain.py` reads its bar from
+`runs/baseline_xgb/summary.json`, and the fine-tuning scripts load pretraining weights.
+
+## A first TCN: `tcn_gestures.py`
+
+A 30-second, data-free introduction to temporal convolutional networks. It fabricates six
+"signs" as noisy sine trajectories over 32 features, gives each take a recording session, holds out
+an entire session, and trains a small residual TCN.
+
+![Train vs unseen-session accuracy on synthetic gestures](../runs/tcn_gestures/curves.png)
+
+Training accuracy reaches ~99% while accuracy on the held-out session levels off near 78%. That gap
+is the point: takes from one session share their noise and timing, so a random split over takes
+would put near-duplicates on both sides and report something much closer to the training curve.
+Hold out whole sessions whenever your data has them.

islkit-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[project]
+name = "islkit"
+version = "0.1.0"
+description = "Indian Sign Language recognition from MediaPipe landmarks: features, a dual-branch TCN, and a live recognition service"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Jayraj" }]
+requires-python = ">=3.12,<3.13"
+keywords = ["sign-language", "isl", "mediapipe", "landmarks", "tcn", "accessibility"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+]
+urls = { Homepage = "https://github.com/jbrathwa/islkit", Issues = "https://github.com/jbrathwa/islkit/issues" }
+dependencies = [
+    "torch>=2.5",
+    # 0.10.18 is pinned exactly and pins numpy<2 behind it. It is the last release
+    # that keeps mp.solutions (1.0.x removed it), and 1.0.x's aarch64 wheel needs
+    # ARMv8.1-A LSE atomics, so it will not run on Cortex-A53 boards.
+    "mediapipe==0.10.18",
+    "numpy>=1.26,<2",
+]
+
+# cv2 is deliberately not declared: mediapipe hard-requires opencv-contrib-python,
+# and adding another OpenCV package on top puts two providers of one module in the
+# environment. matplotlib likewise arrives with mediapipe.
+[project.optional-dependencies]
+train = [
+    "pandas>=3.0.5",
+    "pyarrow>=25.0.1",
+    "xgboost>=3.4.1",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.6",
+]
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/islkit"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/islkit", "tests", "LICENSE", "README.md"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests", "experiments"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

islkit-0.1.0/src/islkit/__init__.py

@@ -0,0 +1,88 @@
+"""islkit — Indian Sign Language recognition from MediaPipe landmarks.
+
+Landmark features, a dual-branch TCN, the INCLUDE loader, live inference and a
+small HTTP/SSE recognition service.
+"""
+
+import importlib
+
+from islkit.baseline import pooled_stats, stratified_folds
+from islkit.data import IncludeData, load_include
+from islkit.features import DIM_FRAME, DIM_GEOM, RawFrame, encode_clip, encode_frame
+from islkit.labels import LabelMap, build_dataset, decode_prediction
+from islkit.metrics import accuracy, confusion_matrix, per_class_f1, top_confusions
+from islkit.plotting import plot_confusion, plot_curves, plot_f1_distribution
+from islkit.viz import animate_replay, reconstruct, still_replay
+
+# device, seeding and model are the only modules that import torch, and they are
+# loaded on first use rather than at import time. Not for speed: torch bundles its
+# own libomp, XGBoost links Homebrew's, and macOS aborts the process when both land
+# in it (OMP Error #15). The XGBoost baseline is pure numpy and must be able to import
+# load_include without dragging torch in behind it. See islkit/baseline.py.
+_LAZY = {
+    "describe_device": "islkit.device",
+    "pick_device": "islkit.device",
+    "set_seed": "islkit.seeding",
+    "Backbone": "islkit.model",
+    "SignClassifier": "islkit.model",
+    "build_model": "islkit.model",
+    "freeze_backbone": "islkit.model",
+    "replace_head": "islkit.model",
+    "ClipStore": "islkit.infer",
+    "ClipTooShort": "islkit.infer",
+    "HolisticExtractor": "islkit.infer",
+    "Prediction": "islkit.infer",
+    "SignRecogniser": "islkit.infer",
+}
+
+
+def __getattr__(name: str):
+    module = _LAZY.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    value = getattr(importlib.import_module(module), name)
+    globals()[name] = value  # bind so this runs once per name
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)
+
+
+__all__ = [
+    "DIM_FRAME",
+    "DIM_GEOM",
+    "Backbone",
+    "ClipStore",
+    "ClipTooShort",
+    "HolisticExtractor",
+    "IncludeData",
+    "LabelMap",
+    "Prediction",
+    "RawFrame",
+    "SignClassifier",
+    "SignRecogniser",
+    "accuracy",
+    "animate_replay",
+    "build_dataset",
+    "build_model",
+    "confusion_matrix",
+    "decode_prediction",
+    "describe_device",
+    "encode_clip",
+    "encode_frame",
+    "freeze_backbone",
+    "load_include",
+    "per_class_f1",
+    "pick_device",
+    "plot_confusion",
+    "plot_curves",
+    "plot_f1_distribution",
+    "pooled_stats",
+    "reconstruct",
+    "replace_head",
+    "set_seed",
+    "still_replay",
+    "stratified_folds",
+    "top_confusions",
+]