weightslab 1.2.2__tar.gz → 1.2.3__tar.gz

{weightslab-1.2.2 → weightslab-1.2.3}/.github/workflows/ci.yml

@@ -95,19 +95,22 @@ jobs:
             echo "$FILES" | xargs vulture --min-confidence 70 ./weightslab || true
           fi
 
+  # ── Fast install gate (always runs) ──────────────────────────────────────
+  # Single-version install on 3.11 — always runs so `test` has a gate to
+  # depend on regardless of branch.
   install:
     if: ${{ github.event_name != 'push' || !startsWith(github.ref, 'refs/tags/') }}
     runs-on: ubuntu-latest
+    name: install (Python 3.11)
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Set up Python
+      - name: Set up Python 3.11
         uses: actions/setup-python@v5
         with:
           python-version: '3.11'
 
-
       - name: Install project dependencies
         run: |
           python -m pip install --upgrade pip
@@ -117,9 +120,49 @@ jobs:
         run: |
           python -c "import weightslab; print(f'weightslab imported successfully')"
 
+  # ── Full Python version matrix (PR and main only) ─────────────────────────
+  # Verifies that `pip install` + basic import work across all supported Python
+  # versions. Runs on every PR and every push to main; skipped on dev/other
+  # branch pushes to avoid unnecessary cost on work-in-progress commits.
+  install-matrix:
+    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false          # keep running other versions if one fails
+      matrix:
+        include:
+          - python-version: '3.10'
+          - python-version: '3.11'
+          - python-version: '3.12'
+          - python-version: '3.13'
+          - python-version: '3.14'
+            allow-prereleases: true   # 3.14 is pre-release; visible failure but non-blocking
+    name: install (Python ${{ matrix.python-version }})
+    # 3.14 pre-release failures are informational — don't block the pipeline.
+    continue-on-error: ${{ matrix.allow-prereleases == true }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: ${{ matrix.allow-prereleases || false }}
+
+      - name: Install project dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e . --extra-index-url https://download.pytorch.org/whl/cpu
+
+      - name: Verify installation
+        run: |
+          python -c "import weightslab; print(f'weightslab imported successfully on Python ${{ matrix.python-version }}')"
+
   test:
     if: ${{ github.event_name != 'push' || !startsWith(github.ref, 'refs/tags/') }}
     runs-on: ubuntu-latest
+    # Depends on the fast 3.11 gate only — the matrix runs independently in parallel.
     needs: install
     steps:
       - name: Checkout repository
@@ -165,7 +208,8 @@ jobs:
       #     echo "WeightsStudio workflow dispatch requested successfully."
 
   build-and-publish-dev:
-    if: ${{ github.event_name != 'push' || !startsWith(github.ref, 'refs/tags/') }}
+    # Only publish to TestPyPI when pushing to main (not on PRs or dev branch pushes).
+    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
     name: Build & Publish Dev (TestPyPI)
     needs: test
     runs-on: ubuntu-latest
@@ -248,18 +292,34 @@ jobs:
           fi
           python -m twine upload --repository-url https://test.pypi.org/legacy/ --verbose dist/*
 
+  # ── Cross-version install test from TestPyPI ──────────────────────────────
+  # Installs the just-published dev package from TestPyPI on every supported
+  # Python version and verifies the import works end-to-end.
+  # Runs only on main branch pushes (same gate as the publish step above).
   test-install-from-pip-dev:
-    if: ${{ github.event_name != 'push' || !startsWith(github.ref, 'refs/tags/') }}
-    name: Test Install From Pip Dev
+    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+    name: Test Install From Pip Dev (Python ${{ matrix.python-version }})
     needs: build-and-publish-dev
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - python-version: '3.10'
+          - python-version: '3.11'
+          - python-version: '3.12'
+          - python-version: '3.13'
+          - python-version: '3.14'
+            allow-prereleases: true
+    continue-on-error: ${{ matrix.allow-prereleases == true }}
     permissions:
       contents: read
     steps:
-      - name: Set up Python
+      - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: ${{ matrix.allow-prereleases || false }}
 
       - name: Create isolated virtual environment
         run: |
@@ -296,9 +356,13 @@ jobs:
           done
 
           python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://download.pytorch.org/whl/cpu --extra-index-url https://pypi.org/simple "weightslab==${WL_VERSION}" --no-cache-dir --retries 10 --timeout 60
-          echo "weightslab==${WL_VERSION} installed from TestPyPI"
+          echo "weightslab==${WL_VERSION} installed from TestPyPI on Python ${{ matrix.python-version }}"
 
       - name: Verify package import
         run: |
           . .venv-ci/bin/activate
-          python -c "import weightslab; import importlib.metadata as m; print('weightslab import OK'); print('installed version:', m.version('weightslab'))"
+          python -c "
+          import weightslab, importlib.metadata as m
+          print('weightslab import OK on Python ${{ matrix.python-version }}')
+          print('installed version:', m.version('weightslab'))
+          "

{weightslab-1.2.2 → weightslab-1.2.3}/.github/workflows/release.yml

@@ -114,16 +114,29 @@ jobs:
           path: dist/
           retention-days: 1
 
+  # ── Cross-version install test from TestPyPI (Dev Release) ───────────────
   test-install-from-pip-dev-release:
-    name: Test Install From TestPyPI (Dev Release)
+    name: Test Install From TestPyPI — Python ${{ matrix.python-version }} (Dev Release)
     needs: build-and-publish-dev-release
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - python-version: '3.10'
+          - python-version: '3.11'
+          - python-version: '3.12'
+          - python-version: '3.13'
+          - python-version: '3.14'
+            allow-prereleases: true
+    continue-on-error: ${{ matrix.allow-prereleases == true }}
     permissions:
       contents: read
     steps:
       - uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: ${{ matrix.allow-prereleases || false }}
 
       - name: Create isolated virtual environment
         run: python -m venv .venv-ci
@@ -159,14 +172,14 @@ jobs:
             --extra-index-url https://pypi.org/simple/ \
             --extra-index-url https://download.pytorch.org/whl/cpu \
             "weightslab==${WL_VERSION}" --no-cache-dir --retries 10 --timeout 60
-          echo "weightslab==${WL_VERSION} installed from TestPyPI"
+          echo "weightslab==${WL_VERSION} installed on Python ${{ matrix.python-version }}"
 
       - name: Verify package import
         run: |
           . .venv-ci/bin/activate
           python -c "
           import weightslab, importlib.metadata as m
-          print('weightslab import OK')
+          print('weightslab import OK on Python ${{ matrix.python-version }}')
           print('installed version:', m.version('weightslab'))
           "
 
@@ -290,7 +303,6 @@ jobs:
 
   build-and-publish-main:
     name: Build & Publish Main (PyPI)
-    # needs: [detect-target, ]
     needs: [detect-target]
     runs-on: ubuntu-latest
     if: ${{ needs.detect-target.outputs.is_main == 'true' }}
@@ -343,16 +355,21 @@ jobs:
           path: dist/
           retention-days: 1
 
+  # ── Cross-version install test from PyPI (Main Release) ──────────────────
   test-install-from-pip-main:
-    name: Test Install From PyPI (Main Release)
+    name: Test Install From PyPI — Python ${{ matrix.python-version }} (Main Release)
     needs: build-and-publish-main
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13']
     permissions:
       contents: read
     steps:
       - uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: ${{ matrix.python-version }}
 
       - name: Create isolated virtual environment
         run: python -m venv .venv-ci
@@ -387,14 +404,14 @@ jobs:
             --index-url https://pypi.org/simple/ \
             --extra-index-url https://download.pytorch.org/whl/cpu \
             "weightslab==${WL_VERSION}" --no-cache-dir --retries 10 --timeout 60
-          echo "weightslab==${WL_VERSION} installed from PyPI"
+          echo "weightslab==${WL_VERSION} installed on Python ${{ matrix.python-version }}"
 
       - name: Verify package import
         run: |
           . .venv-ci/bin/activate
           python -c "
           import weightslab, importlib.metadata as m
-          print('weightslab import OK')
+          print('weightslab import OK on Python ${{ matrix.python-version }}')
           print('installed version:', m.version('weightslab'))
           "
 

{weightslab-1.2.2 → weightslab-1.2.3}/.gitignore

@@ -10,6 +10,7 @@ __pycache__
 venv
 runs
 data
+MagicMock
 
 # Ignore hidden directories
 .history

weightslab-1.2.3/CHANGELOG.md

@@ -0,0 +1 @@
+# Changelog - 2026-06-12 v1.2.3 (1)

{weightslab-1.2.2/weightslab.egg-info → weightslab-1.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: weightslab
-Version: 1.2.2
+Version: 1.2.3
 Summary: Paving the way between black-box and white-box modeling.
 Author-email: Alexandru-Andrei Rotaru <alexandru@graybx.com>, Guillaue Pelluet <guillaue@graybx.com>
 License: BSD 2-clause

{weightslab-1.2.2 → weightslab-1.2.3}/weightslab/__init__.py

@@ -14,7 +14,7 @@ import threading
 from .src import watch_or_edit, start_training, serve, keep_serving, save_signals, save_instance_signals, save_group_signals, tag_samples, register_categorical_tag, set_categorical_tag, discard_samples, get_samples_by_tag, get_discarded_samples, signal, eval_fn, compute_signals, SignalContext, clear_all, run_pending_evaluation, trigger_pending_evaluation_async, query_signal_history, query_sample_history, query_instance_history, write_history, write_dataframe, get_current_experiment_hash, pointcloud_thumbnail, pointcloud_boxes
 from .backend.ledgers import GLOBAL_LEDGER as ledger
 from .art import _BANNER
-from .utils.logs import setup_logging, set_log_directory
+from .utils.logs import setup_logging, set_log_directory, is_main_process
 from .utils.tools import seed_everything
 from .components.global_monitoring import guard_training_context, guard_testing_context
 
@@ -25,21 +25,27 @@ from .components.global_monitoring import guard_training_context, guard_testing_
 # Change the name of the current (main) thread
 threading.current_thread().name = "WL-MainThread"
 
-# Auto-initialize logging on import. Python's module cache (sys.modules) guarantees
-# this block runs exactly once per process. Subprocesses get a fresh interpreter
-# and initialize independently — no env var needed to coordinate across processes.
+# Auto-initialize logging on import. Python's module cache (sys.modules) makes
+# this block run once per process — but spawned/forked workers (e.g. PyTorch
+# DataLoader workers, which on Windows' 'spawn' start method re-import this
+# package) are separate processes and would each re-emit the banner and create
+# their own temp log file during training. The noisy parts below are therefore
+# gated to the main process; workers keep a quiet console-only logger.
 log_level = os.getenv('WEIGHTSLAB_LOG_LEVEL', 'INFO')
 log_to_file = os.getenv('WEIGHTSLAB_LOG_TO_FILE', 'true').lower() == 'true'
 
-setup_logging(log_level, log_to_file=log_to_file)
+_IS_MAIN_PROCESS = is_main_process()
+
+setup_logging(log_level, log_to_file=(log_to_file and _IS_MAIN_PROCESS))
 
 logger = logging.getLogger(__name__)
-logger.info(f"WeightsLab package initialized - Log level: {log_level}, Log to file: {log_to_file}")
-if os.getenv('WEIGHTSLAB_SUPPRESS_BANNER', '0') != '1':
-	logger.info(_BANNER)
+if _IS_MAIN_PROCESS:
+    logger.info(f"WeightsLab package initialized - Log level: {log_level}, Log to file: {log_to_file}")
+    if os.getenv('WEIGHTSLAB_SUPPRESS_BANNER', '0') != '1':
+        logger.info(_BANNER)
 
 grpc_tls_enabled = os.environ.get('GRPC_TLS_ENABLED', 'true').lower() == 'true'
-if grpc_tls_enabled and os.environ.get('WEIGHTSLAB_SKIP_SECURE_INIT', 'false').lower() != 'true':
+if _IS_MAIN_PROCESS and grpc_tls_enabled and os.environ.get('WEIGHTSLAB_SKIP_SECURE_INIT', 'false').lower() != 'true':
 	try:
 		from weightslab.security import CertAuthManager
 

{weightslab-1.2.2 → weightslab-1.2.3}/weightslab/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.2.2'
-__version_tuple__ = version_tuple = (1, 2, 2)
+__version__ = version = '1.2.3'
+__version_tuple__ = version_tuple = (1, 2, 3)
 
-__commit_id__ = commit_id = 'gffeacaaf3'
+__commit_id__ = commit_id = 'g27ecce886'

{weightslab-1.2.2 → weightslab-1.2.3}/weightslab/backend/dataloader_interface.py

@@ -443,6 +443,9 @@ class DataLoaderInterface:
         self.is_training = kwargs.pop("is_training", False)
         self._enable_h5_persistence = kwargs.pop("enable_h5_persistence", True)
         self.skip_previous_auto_load = kwargs.pop("skip_previous_auto_load", False)
+        # Captured so we can default it intelligently (see _should_persist_workers).
+        # Popped here so it never reaches DataLoader/wrapper twice via **kwargs.
+        self._user_persistent_workers = kwargs.pop("persistent_workers", None)
 
         # Init ledgered HP
         self.hp = get_hyperparams()
@@ -513,6 +516,7 @@ class DataLoaderInterface:
                 num_workers=num_workers,
                 pin_memory=pin_memory,
                 collate_fn=collate_fn,
+                persistent_workers=self._should_persist_workers(num_workers),
                 **filter_kwargs_for_callable(DataLoader, kwargs)
             )
             self._mutable_batch_sampler = batch_sampler
@@ -952,6 +956,29 @@ class DataLoaderInterface:
     #         self._skipped = []
     #         self._sample_offset = 0
 
+    def _should_persist_workers(self, num_workers: int) -> bool:
+        """Whether to keep DataLoader workers alive across iterator resets.
+
+        With num_workers > 0 and persistent_workers=False, every `_reset_iterator()`
+        (each epoch boundary, batch-size change, RNG restore) tears down and
+        re-spawns all worker processes. On Windows ('spawn') each respawn
+        re-imports torch + weightslab + the dataset module — hundreds of ms to
+        seconds per reset. Persisting workers makes the reset a cheap re-shuffle.
+
+        Safe because discards/eval filtering happen in the main-process sampler
+        (WeightsLabDataSampler, re-iterated every epoch) and the dataset's
+        idx->sample mapping is immutable. The one exception is tag-based
+        relabeling (use_tags=True): __getitem__ then reads live tags, which
+        today only reach workers via the per-epoch respawn — so keep respawning
+        in that case. An explicit persistent_workers= kwarg always wins.
+        """
+        if num_workers <= 0:
+            return False
+        if self._user_persistent_workers is not None:
+            return bool(self._user_persistent_workers)
+        use_tags_active = bool(getattr(self.tracked_dataset, "_use_tags", False))
+        return not use_tags_active
+
     def _reset_iterator(self) -> None:
         """Reset the internal iterator so `_next_batch()` starts from the beginning.
 
@@ -962,6 +989,14 @@ class DataLoaderInterface:
         import gc
         import time
 
+        # Workers are only torn down and re-spawned when they DON'T persist. When
+        # persistent_workers is on, iter(self.dataloader) reuses the live workers
+        # (a cheap re-shuffle), so the GC sweep and settle-delay below are pure
+        # overhead and are skipped.
+        num_workers = getattr(self.dataloader, 'num_workers', 0) or 0
+        persistent = bool(getattr(self.dataloader, 'persistent_workers', False))
+        respawning = num_workers > 0 and not persistent
+
         # Explicitly delete old iterator to allow worker processes to be cleaned up
         if hasattr(self, '_iterator') and self._iterator is not None:
             try:
@@ -970,12 +1005,13 @@ class DataLoaderInterface:
             except Exception as e:
                 logger.debug(f"Failed to delete old iterator: {e}")
 
-        # Force garbage collection to ensure worker processes are terminated
-        # This is especially important when num_workers > 0
-        try:
-            gc.collect()
-        except Exception:
-            pass
+        # Force garbage collection to ensure worker processes are terminated.
+        # Only needed when workers are actually being torn down (non-persistent).
+        if respawning:
+            try:
+                gc.collect()
+            except Exception:
+                pass
 
         # Reset sampler's offset for new epoch (important: prevents skipping samples on subsequent epochs)
         if hasattr(self, '_mutable_batch_sampler') and self._mutable_batch_sampler is not None:
@@ -985,9 +1021,10 @@ class DataLoaderInterface:
                 if old_offset > 0:
                     logger.debug(f"Reset sampler offset from {old_offset} to 0")
 
-        # Give worker processes time to fully terminate (especially important with num_workers > 0)
-        # Short delay to avoid race conditions when spawning new workers
-        if hasattr(self.dataloader, 'num_workers') and self.dataloader.num_workers > 0:
+        # Give worker processes time to fully terminate before spawning new ones.
+        # Only relevant when workers are actually respawning; persistent workers
+        # stay alive, so no settle-delay is needed.
+        if respawning:
             time.sleep(0.01)  # 10ms delay for worker cleanup
 
         # Create new iterator
@@ -1168,6 +1205,7 @@ class DataLoaderInterface:
                         num_workers=num_workers,
                         pin_memory=pin_memory,
                         collate_fn=collate_fn,
+                        persistent_workers=self._should_persist_workers(num_workers),
                         **kwargs,
                     )
                 else:
@@ -1180,6 +1218,7 @@ class DataLoaderInterface:
                         drop_last=drop_last,
                         pin_memory=pin_memory,
                         collate_fn=collate_fn,
+                        persistent_workers=self._should_persist_workers(num_workers),
                         **kwargs,
                     )
 

{weightslab-1.2.2 → weightslab-1.2.3}/weightslab/components/global_monitoring.py

@@ -214,11 +214,13 @@ class GuardContext:
         except Exception:
             pass
 
-    def __enter__(self):
+    def __enter__(self, f: bool = False):
         """
         Executed upon entering the 'with' block. Sets the model to training mode.
         """
         self._maybe_pause_at_step()
+        if f:
+            pause_controller.resume(force=f)
         pause_controller.wait_if_paused()
         self.architecture_guard.__enter__()
 
@@ -266,11 +268,15 @@ class GuardContext:
                 self.model.set_tracking_mode(TrackingMode.EVAL)
                 self.model.eval()
 
-    def __exit__(self, exc_type: Any, exc_value: Any, traceback: Any) -> bool:
+    def __exit__(self, exc_type: Any, exc_value: Any, traceback: Any, f: bool = False) -> bool:
         """
         Executed upon exiting the 'with' block (after user code runs).
         Reverts the model state.
         """
+
+        if f:
+            pause_controller.pause()
+
         # Revert the model state
         if self.model is not None and hasattr(self, '_prev_training_mode'):
             self.model.train(self._prev_training_mode)

{weightslab-1.2.2 → weightslab-1.2.3}/weightslab/data/dataframe_manager.py

@@ -1049,7 +1049,7 @@ class LedgeredDataFrameManager:
             if v is None:
                 return False
             try:
-                return not np.isnan(v)
+                return not np.isnan(v).any()
             except (TypeError, ValueError):
                 return True
 
@@ -2378,7 +2378,7 @@ class LedgeredDataFrameManager:
         logger.debug(f"[LedgeredDataFrameManager] Waiting for buffer to drain. Buffer size: {len(self._buffer)}.")
         while time.time() < deadline:
             with self._buffer_lock:
-                logger.debug(f"[LedgeredDataFrameManager] Acquiring buffer lock for flush_async check. Buffer size: {len(self._buffer)}.")
+                # logger.debug(f"[LedgeredDataFrameManager] Acquiring buffer lock for flush_async check. Buffer size: {len(self._buffer)}.")
                 if len(self._buffer) < self._flush_max_rows:
                     logger.debug(f"[LedgeredDataFrameManager] Buffer drained, proceeding. Buffer size: {len(self._buffer)}.")
                     return

weightslab-1.2.3/weightslab/examples/Docker_training/README.md

@@ -0,0 +1,38 @@
+# Running WeightsLab from a "training docker" — three options
+
+Each option runs the WeightsLab UI stack + the classification training inside a
+container so the example ends up reachable at <http://localhost:5173>, talking to
+the training process end-to-end. They differ in **how the container gets a docker
+daemon** to launch Envoy + frontend, and the configuration that follows.
+
+| | [docker_in_docker](docker_in_docker/) (A · DinD) | [siblings_docker](siblings_docker/) (B · DooD) | [siblings_self_contained](siblings_self_contained/) (C) |
+|---|---|---|---|
+| Docker daemon | own daemon, nested | host daemon (socket) | host daemon (socket) |
+| Envoy/frontend run | nested in the trainer | siblings on the host | siblings on the host |
+| Starts the UI via | `weightslab ui launch` | `weightslab ui launch` | own bind-mount-free `ui-compose.yml` |
+| `--privileged` | **required** | no | no |
+| gRPC `:50051` | not published | **published to host** | **published to host** |
+| Browser ports 5173/8080 | re-published by trainer | published by siblings | published by siblings |
+| Host bind mounts | resolve in-container — none | **path alignment** required | **none** (config via named volume + HTTP) |
+| Host setup | none | `setup-host.sh` (clone to aligned path) | none |
+| TLS (HTTPS) | ✅ `--certs` (+ backend TLS env) | ✅ `--certs` (aligned certs) | ✅ opt-in (certs via named volume) |
+| Windows / Docker Desktop | ✅ works | ⚠️ awkward (use WSL2) | ✅ works natively |
+| Best when | want isolation / Windows / TLS | Linux host, stock `ui launch` | "all from inside", no host prep, Windows |
+
+See each directory's `README.md` for the detailed wiring diagram and run steps.
+
+- **A (DinD)** — fully self-contained via a nested daemon; needs `--privileged`.
+- **B (siblings)** — uses the stock `weightslab ui launch`; its bundled compose
+  bind-mounts the Envoy config + certs, so the host must see those files (path
+  alignment + `setup-host.sh`). Cleanest on a Linux host.
+- **C (self-contained siblings)** — siblings *without* host bind mounts: it
+  delivers the Envoy config (and, for TLS, the certs) through named volumes over
+  the socket, so no host prep and it works natively on Windows. The trade-off:
+  it doesn't use `weightslab ui launch`. HTTP by default, TLS opt-in.
+
+> All three can run secured TLS — see each README's "🔒" section. **A and C
+> expose a one-flag toggle:** `WEIGHTSLAB_TLS=1 docker compose up --build`. Note
+> that for **every** option cert generation only configures Envoy + the frontend;
+> the **backend** example also needs `GRPC_TLS_ENABLED=1` + `GRPC_TLS_CERT_DIR`
+> (the toggle handles this), or Envoy's upstream mTLS fails. And the dev CA must
+> be trusted on the host browser to avoid a self-signed warning.

weightslab-1.2.3/weightslab/examples/Docker_training/docker_in_docker/Dockerfile

@@ -0,0 +1,58 @@
+# =============================================================================
+# WeightsLab "training docker" — Docker-in-Docker (DinD) variant
+# =============================================================================
+# This image runs BOTH:
+#   1. the WeightsLab CLI ("weightslab ui launch") which spins up the
+#      Envoy + Weights Studio frontend containers, and
+#   2. the training process ("weightslab start example") which serves the
+#      in-process gRPC backend on :50051.
+#
+# DinD = the container runs its OWN docker daemon inside itself (requires
+# --privileged). The Envoy/frontend containers are nested *inside* this
+# container's daemon, so they share this container's network namespace and
+# filesystem. See README.md for why that matters.
+# =============================================================================
+FROM python:3.11-slim
+
+# --- System deps -------------------------------------------------------------
+# - docker engine (dockerd + CLI + compose plugin + containerd): installed via
+#   the official convenience script. We need the *daemon* here (DinD).
+# - libgl1/libglib2.0-0: runtime libs for opencv-python (a weightslab dep).
+# - curl/ca-certificates/git: fetch the docker installer + optional dev install.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        curl sudo ca-certificates git libgl1 libglib2.0-0 \
+    && curl -fsSL https://get.docker.com | sh \
+    && rm -rf /var/lib/apt/lists/*
+
+# --- WeightsLab --------------------------------------------------------------
+# Default: install the published package from PyPI (matches "if you didn't
+# modify weightslab, use pip install"). To run your local dev branch instead:
+#   docker compose build \
+#     --build-arg WEIGHTSLAB_SPEC="git+https://github.com/GrayboxTech/weightslab.git@dev"
+ARG WEIGHTSLAB_SPEC=weightslab
+RUN pip install --no-cache-dir "${WEIGHTSLAB_SPEC}"
+
+# gRPC backend port — must match what Envoy is told to dial (GRPC_BACKEND_PORT).
+ENV GRPC_BACKEND_PORT=50051
+
+# --- GPU (NVIDIA) ------------------------------------------------------------
+# Make the NVIDIA Container Toolkit inject the host driver (nvidia-smi + libs)
+# into this container. `utility` => nvidia-smi works; `compute` => CUDA/torch.
+# These are no-ops on a host without an NVIDIA GPU/toolkit (falls back to CPU).
+# The actual GPU grant is requested in docker-compose.yml (deploy.resources).
+# torch's default Linux wheel bundles the CUDA runtime, so no CUDA base image is
+# needed — only the host driver (injected) is required for torch.cuda to work.
+ENV NVIDIA_VISIBLE_DEVICES=all \
+    NVIDIA_DRIVER_CAPABILITIES=compute,utility
+
+COPY entrypoint.sh /usr/local/bin/entrypoint.sh
+# Strip any CR so the script runs under Linux bash even if checked out on Windows.
+RUN sed -i 's/\r$//' /usr/local/bin/entrypoint.sh \
+    && chmod +x /usr/local/bin/entrypoint.sh
+
+# OPTIONAL - Documentation only — EXPOSE does NOT publish ports. The host publishing is done
+# by `ports:` in docker-compose.yml. Listed here purely to record intent:
+#   5173 = Weights Studio frontend, 8080 = Envoy gRPC-web.
+EXPOSE 5173 8080
+
+ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]