v1.3.3: Release — Collab integration, UI improvements, CLI enhancements, and agent features

.gitignore

@@ -11,11 +11,15 @@ venv
 runs
 data
 MagicMock
+drop
+htmlcov
+htmlcov-report
 
 # Ignore hidden directories
 .history
 .lh
 .claude
+.coverage
 .chat
 .ai
 .pytest_cache

CHANGELOG.md

@@ -1 +1 @@
-# Changelog - 2026-07-07 v1.3.2
+# Changelog - 2026-07-10 v1.3.3-dev0

docs/_static/custom.css

@@ -277,6 +277,35 @@ body[data-theme="dark"] .wl-only-dark {
   margin-bottom: 1rem;
 }
 
+.wl-eg-cardwrap {
+  position: relative;
+  display: flex;
+}
+
+.wl-eg-cardwrap > .wl-eg-card {
+  flex: 1;
+}
+
+/* "Open in Colab" logo, pinned top-right, above the card link. */
+.wl-eg-colab {
+  position: absolute;
+  right: 0.9rem;
+  top: 0.9rem;
+  z-index: 2;
+  line-height: 0;
+  transition: transform 0.12s;
+}
+
+.wl-eg-colab:hover {
+  transform: scale(1.1);
+}
+
+.wl-eg-colab img {
+  height: 22px;
+  width: 22px;
+  display: block;
+}
+
 .wl-eg-card {
   display: flex;
   flex-direction: column;

docs/_static/examples-gallery.js

@@ -10,41 +10,49 @@
   ];
 
   // URLs are root-relative (from the doc root), prefixed with content_root at render time
+  // Base for "Open in Colab" links (notebooks live under examples/Notebooks).
+  var COLAB = 'https://colab.research.google.com/github/GrayboxTech/weightslab/blob/main/weightslab/examples/Notebooks/';
+
   var EXAMPLES = [
     {
       badge: 'PyTorch', color: 'pytorch',
       title: 'Classification — MNIST',
       desc: 'CNN digit classifier on MNIST. Register hyperparameters, monitor per-sample loss, and use the deny-aware sampler to focus on hard examples.',
       tags: ['classification', 'supervised', 'mnist', 'cnn'],
-      url: 'examples/pytorch/classification.html'
+      url: 'examples/pytorch/classification.html',
+      colab: COLAB + 'PyTorch/ws-classification.ipynb'
     },
     {
       badge: 'PyTorch', color: 'pytorch',
       title: 'Segmentation — BDD100k',
       desc: 'Per-pixel semantic segmentation with a UNet. Track per-sample IoU and visualise mask overlays directly in the studio.',
       tags: ['segmentation', 'semantic', 'bdd100k', 'masks', 'dense prediction'],
-      url: 'examples/pytorch/segmentation.html'
+      url: 'examples/pytorch/segmentation.html',
+      colab: COLAB + 'PyTorch/ws-segmentation.ipynb'
     },
     {
       badge: 'PyTorch', color: 'pytorch',
       title: 'Detection — Penn-Fudan',
       desc: 'Bounding-box detection on Penn-Fudan pedestrians. Per-instance multi-index dataframe with (sample_id, annotation_id) keys.',
       tags: ['detection', 'object detection', 'bounding boxes', 'penn-fudan'],
-      url: 'examples/pytorch/detection.html'
+      url: 'examples/pytorch/detection.html',
+      colab: COLAB + 'PyTorch/ws-detection.ipynb'
     },
     {
       badge: 'PyTorch', color: 'pytorch',
       title: 'Clustering — Face Recognition',
       desc: 'Metric learning with triplet loss on face datasets. Store and explore high-dimensional embeddings per sample in the studio.',
       tags: ['clustering', 'unsupervised', 'embeddings', 'face recognition', 'metric learning'],
-      url: 'examples/pytorch/clustering.html'
+      url: 'examples/pytorch/clustering.html',
+      colab: COLAB + 'PyTorch/ws-clustering.ipynb'
     },
     {
       badge: 'PyTorch', color: 'pytorch',
       title: 'Generation / Anomaly Detection',
       desc: 'Unsupervised anomaly detection on MVTec with a multi-task UNet. Monitor reconstruction quality and per-sample anomaly scores.',
       tags: ['anomaly detection', 'generation', 'unsupervised', 'mvtec', 'reconstruction'],
-      url: 'examples/pytorch/generation.html'
+      url: 'examples/pytorch/generation.html',
+      colab: COLAB + 'PyTorch/ws-generation.ipynb'
     },
     {
       badge: 'Lightning', color: 'lightning',
@@ -72,7 +80,8 @@
       title: 'Loss-Shape Classification',
       desc: 'Dynamic subscribed signal that classifies each sample\'s loss trajectory (monotonic, U-shape, spiked, …) and auto-tags it.',
       tags: ['loss analysis', 'signal', 'categorical tag', 'per-sample', 'trajectory'],
-      url: 'examples/usecases/loss_shape_classification.html'
+      url: 'examples/usecases/loss_shape_classification.html',
+      colab: COLAB + 'Usecases/ws-segmentation-loss-shapes.ipynb'
     }
   ];
 
@@ -94,15 +103,25 @@
     }).join('');
     var search = (ex.title + ' ' + ex.tags.join(' ')).toLowerCase();
     var href = baseUrl + '/' + ex.url;
+    // "Open in Colab" badge, bottom-right, as a sibling of the card link (an
+    // <a> cannot be nested inside another <a>). Only for examples with a notebook.
+    var colabHtml = ex.colab
+      ? '<a class="wl-eg-colab" href="' + esc(ex.colab) + '" target="_blank" rel="noopener noreferrer" title="Open in Google Colab" aria-label="Open in Google Colab">' +
+          '<img src="https://colab.research.google.com/img/colab_favicon_256px.png" alt="Open in Colab">' +
+        '</a>'
+      : '';
+    // The wrapper carries the filter data so the whole card (badge included)
+    // shows/hides together.
     return (
-      '<a class="wl-eg-card" href="' + esc(href) + '"' +
-        ' data-search="' + esc(search) + '"' +
-        ' data-color="' + esc(ex.color) + '">' +
-        '<span class="wl-eg-badge wl-eg-badge--' + ex.color + '">' + esc(ex.badge) + '</span>' +
-        '<p class="wl-eg-title">' + esc(ex.title) + '</p>' +
-        '<p class="wl-eg-desc">' + esc(ex.desc) + '</p>' +
-        '<div class="wl-eg-tags">' + tagsHtml + '</div>' +
-      '</a>'
+      '<div class="wl-eg-cardwrap" data-search="' + esc(search) + '" data-color="' + esc(ex.color) + '">' +
+        '<a class="wl-eg-card" href="' + esc(href) + '">' +
+          '<span class="wl-eg-badge wl-eg-badge--' + ex.color + '">' + esc(ex.badge) + '</span>' +
+          '<p class="wl-eg-title">' + esc(ex.title) + '</p>' +
+          '<p class="wl-eg-desc">' + esc(ex.desc) + '</p>' +
+          '<div class="wl-eg-tags">' + tagsHtml + '</div>' +
+        '</a>' +
+        colabHtml +
+      '</div>'
     );
   }
 
@@ -166,7 +185,7 @@
       var totalVisible = 0;
 
       document.querySelectorAll('.wl-eg-section').forEach(function (section) {
-        var cards = section.querySelectorAll('.wl-eg-card');
+        var cards = section.querySelectorAll('.wl-eg-cardwrap');
         var sectionVisible = 0;
         cards.forEach(function (c) {
           var matchText  = !q || c.dataset.search.indexOf(q) !== -1;

docs/examples/lightning/classification.rst

@@ -11,7 +11,7 @@ Classification — MNIST (PyTorch Lightning)
      <span class="wl-eg-tag">pytorch lightning</span>
    </div>
 
-**Example:** ``weightslab/examples/Lightning/ws-classification/main.py``
+**Example:** ``weightslab/examples/Lightning/wl-classification/main.py``
 
 **Task:** MNIST digit classification with a CNN, training loop managed by
 ``pl.Trainer``.

docs/examples/pytorch/classification.rst

@@ -11,7 +11,7 @@ Classification — MNIST (PyTorch)
      <span class="wl-eg-tag">cnn</span>
    </div>
 
-**Example:** ``weightslab/examples/PyTorch/ws-classification/main.py``
+**Example:** ``weightslab/examples/PyTorch/wl-classification/main.py``
 
 **Task:** 10-class digit classification on MNIST with a small CNN.
 
@@ -159,3 +159,12 @@ debug values, custom distances, etc.
 
       weightslab ui launch           # 1. deploy the studio
       weightslab start example --cls # 2. start the classification demo
+
+
+.. raw:: html
+
+   <div style="text-align:right; margin-top:2rem;">
+     <a href="https://colab.research.google.com/github/GrayboxTech/weightslab/blob/main/weightslab/examples/Notebooks/PyTorch/ws-classification.ipynb" target="_blank" rel="noopener noreferrer">
+       <img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab">
+     </a>
+   </div>

docs/examples/pytorch/clustering.rst

@@ -12,7 +12,7 @@ Clustering — Face Recognition (PyTorch)
      <span class="wl-eg-tag">metric learning</span>
    </div>
 
-**Example:** ``weightslab/examples/PyTorch/ws-clustering/main.py``
+**Example:** ``weightslab/examples/PyTorch/wl-clustering/main.py``
 
 **Task:** Metric learning with triplet loss on the Olivetti / LFW face dataset.
 The goal is to train an embedding network so that embeddings from the same
@@ -95,3 +95,12 @@ silhouette score to identify consistently confused identities.
 
       weightslab ui launch            # 1. deploy the studio
       weightslab start example --clus # 2. start the clustering demo
+
+
+.. raw:: html
+
+   <div style="text-align:right; margin-top:2rem;">
+     <a href="https://colab.research.google.com/github/GrayboxTech/weightslab/blob/main/weightslab/examples/Notebooks/PyTorch/ws-clustering.ipynb" target="_blank" rel="noopener noreferrer">
+       <img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab">
+     </a>
+   </div>

docs/examples/pytorch/detection.rst

@@ -11,7 +11,7 @@ Detection — Penn-Fudan Pedestrians (PyTorch)
      <span class="wl-eg-tag">penn-fudan</span>
    </div>
 
-**Example:** ``weightslab/examples/PyTorch/ws-detection/main.py``
+**Example:** ``weightslab/examples/PyTorch/wl-detection/main.py``
 
 **Task:** Bounding-box detection on the Penn-Fudan pedestrian dataset with a
 small ResNet-backbone detector.
@@ -127,3 +127,12 @@ pipeline. See :ref:`good-practice-get-items` for the recommended signature.
 
       weightslab ui launch           # 1. deploy the studio
       weightslab start example --det # 2. start the detection demo
+
+
+.. raw:: html
+
+   <div style="text-align:right; margin-top:2rem;">
+     <a href="https://colab.research.google.com/github/GrayboxTech/weightslab/blob/main/weightslab/examples/Notebooks/PyTorch/ws-detection.ipynb" target="_blank" rel="noopener noreferrer">
+       <img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab">
+     </a>
+   </div>

docs/examples/pytorch/generation.rst

@@ -12,7 +12,7 @@ Generation / Anomaly Detection — MVTec (PyTorch)
      <span class="wl-eg-tag">reconstruction</span>
    </div>
 
-**Example:** ``weightslab/examples/PyTorch/ws-generation/main.py``
+**Example:** ``weightslab/examples/PyTorch/wl-generation/main.py``
 
 **Task:** Unsupervised anomaly detection on MVTec capsule images with a
 multi-task UNet (classification head + reconstruction head + contrastive loss).
@@ -101,3 +101,12 @@ filter by pair distance to find the hardest negatives.
 
       weightslab ui launch           # 1. deploy the studio
       weightslab start example --gen # 2. start the generation / anomaly demo
+
+
+.. raw:: html
+
+   <div style="text-align:right; margin-top:2rem;">
+     <a href="https://colab.research.google.com/github/GrayboxTech/weightslab/blob/main/weightslab/examples/Notebooks/PyTorch/ws-generation.ipynb" target="_blank" rel="noopener noreferrer">
+       <img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab">
+     </a>
+   </div>

docs/examples/pytorch/segmentation.rst

@@ -12,7 +12,7 @@ Segmentation — BDD100k (PyTorch)
      <span class="wl-eg-tag">dense prediction</span>
    </div>
 
-**Example:** ``weightslab/examples/PyTorch/ws-segmentation/main.py``
+**Example:** ``weightslab/examples/PyTorch/wl-segmentation/main.py``
 
 **Task:** Per-instance semantic segmentation on BDD100k (6 classes) with a
 small UNet.
@@ -114,3 +114,12 @@ these signals over training steps and lets you sort samples by them.
 
       weightslab ui launch           # 1. deploy the studio
       weightslab start example --seg # 2. start the segmentation demo
+
+
+.. raw:: html
+
+   <div style="text-align:right; margin-top:2rem;">
+     <a href="https://colab.research.google.com/github/GrayboxTech/weightslab/blob/main/weightslab/examples/Notebooks/PyTorch/ws-segmentation.ipynb" target="_blank" rel="noopener noreferrer">
+       <img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab">
+     </a>
+   </div>

docs/examples/ultralytics/detection.rst

@@ -16,7 +16,7 @@ The full Ultralytics integration documentation is at :doc:`/ultralytics`.
 This page summarises what ``WLAwareTrainer`` handles automatically and where
 the example lives.
 
-**Example:** ``weightslab/examples/Ultralytics/ws-detection/main.py``
+**Example:** ``weightslab/examples/Ultralytics/wl-detection/main.py``
 
 What the example does
 ---------------------

docs/examples/usecases/lidar_detection.rst

@@ -14,8 +14,8 @@ LiDAR Detection — 2D and 3D (PyTorch)
 
 **Examples:**
 
-- ``weightslab/examples/Usecases/ws-2d-lidar-detection/main.py``
-- ``weightslab/examples/Usecases/ws-3d-lidar-detection/main.py``
+- ``weightslab/examples/Usecases/wl-2d-lidar-detection/main.py``
+- ``weightslab/examples/Usecases/wl-3d-lidar-detection/main.py``
 
 **Task:** Object detection on LiDAR point clouds — 2D pillar-grid (BEV) and
 full 3D bounding boxes (KITTI-format).

docs/examples/usecases/loss_shape_classification.rst

@@ -12,7 +12,7 @@ Loss-Shape Classification per Sample
      <span class="wl-eg-tag">trajectory</span>
    </div>
 
-**Example:** ``weightslab/examples/Usecases/ws-loss_shapes_classification_per_sample/``
+**Example:** ``weightslab/examples/Usecases/wl-loss_shapes_classification_per_sample/``
 
 This use case builds on :doc:`../pytorch/detection` (same Penn-Fudan dataset,
 same model, same ``guard_training_context`` pattern) and adds one new feature:
@@ -208,3 +208,12 @@ Workflow in the studio
 
    To run the full loss-shape example (with the ``@wl.signal(subscribe_to=...)``
    classifier active), use the direct path above.
+
+
+.. raw:: html
+
+   <div style="text-align:right; margin-top:2rem;">
+     <a href="https://colab.research.google.com/github/GrayboxTech/weightslab/blob/main/weightslab/examples/Notebooks/Usecases/ws-segmentation-loss-shapes.ipynb" target="_blank" rel="noopener noreferrer">
+       <img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab">
+     </a>
+   </div>

docs/pytorch_lightning.rst

@@ -3,7 +3,7 @@ PyTorch Lightning Integration
 
 Weightslab is compatible with PyTorch Lightning and already includes a full example:
 
-``weightslab/examples/PyTorch_Lightning/ws-classification/main.py``
+``weightslab/examples/PyTorch_Lightning/wl-classification/main.py``
 
 This page explains how to integrate Weightslab in a Lightning workflow and scale to multiple GPUs.
 
@@ -109,7 +109,7 @@ Optional YAML-driven trainer config
 
 The Lightning example already includes a ready template at:
 
-``weightslab/examples/PyTorch_Lightning/ws-classification/config.yaml``
+``weightslab/examples/PyTorch_Lightning/wl-classification/config.yaml``
 
 .. code-block:: yaml
 

docs/segmentation_usecase.rst

@@ -3,7 +3,7 @@ Segmentation Use Case — Per-instance & Per-sample Signals (PyTorch)
 
 This page walks through the segmentation integration from:
 
-``weightslab/examples/PyTorch/ws-segmentation/main.py``
+``weightslab/examples/PyTorch/wl-segmentation/main.py``
 
 It builds on the classification :doc:`usecases` page and focuses on what is
 **specific to segmentation**: a *list of per-instance masks* per sample, a custom

docs/ultralytics.rst

@@ -8,7 +8,7 @@ without touching the model or YOLO's training loop.
 
 The full example lives at:
 
-``weightslab/examples/Ultralytics/ws-detection/``
+``weightslab/examples/Ultralytics/wl-detection/``
 
 How it works
 ------------
@@ -207,7 +207,7 @@ Running the bundled example
 
    .. code-block:: bash
 
-      python weightslab/examples/Ultralytics/ws-detection/main.py
+      python weightslab/examples/Ultralytics/wl-detection/main.py
 
 5. Open ``http://localhost:5173`` to monitor training, inspect per-sample
    signals, tag difficult images, and discard outliers.

docs/usecases.rst

@@ -3,7 +3,7 @@ Use Case Example (PyTorch)
 
 This page walks through the real MNIST classification integration from:
 
-``weightslab/examples/PyTorch/ws-classification/main.py``
+``weightslab/examples/PyTorch/wl-classification/main.py``
 
 Goal
 ----