weightslab 1.3.2__tar.gz → 1.4.0__tar.gz

{weightslab-1.3.2 → weightslab-1.4.0}/.github/workflows/ci.yml

@@ -221,7 +221,7 @@ jobs:
         run: |
           export WEIGHTSLAB_LOG_LEVEL="DEBUG"
           # A per-test timeout guards against any regression that hangs a test.
-          python -m pytest ./tests -v --timeout=300
+          python -m pytest ./tests -v --timeout=600
 
   build-and-publish-dev:
     # Only publish to TestPyPI when pushing to main (not on PRs or dev branch pushes).

{weightslab-1.3.2 → weightslab-1.4.0}/.github/workflows/release.yml

@@ -7,9 +7,25 @@ on:
 
 jobs:
   # ── Routing ───────────────────────────────────────────────────────────────
-  # Detect whether the tagged commit lives on main (→ PyPI production release)
-  # or anywhere else (→ TestPyPI pre-release).  All downstream jobs branch on
-  # this output so only the correct path runs.
+  # Two independent signals decide what runs, checked in this priority order:
+  #   1. is_dev_release: the tag NAME contains "dev" (e.g. v1.3.1-dev0) —
+  #      ALWAYS true in that case, regardless of which branch/commit is
+  #      tagged. Always publishes to TestPyPI + a GitHub pre-release.
+  #   2. is_main: only considered when the name does NOT contain "dev", and
+  #      requires the tag's commit to actually be an ancestor of main. This is
+  #      a safety gate: a non-dev-named tag cut from a branch other than main
+  #      must never auto-publish a real PyPI release under a "real" version
+  #      number just because someone forgot the branch they were on.
+  # A non-dev-named tag whose commit is NOT on main matches neither and
+  # triggers nothing at all (should_run=false) — accidental/misplaced tags
+  # never release.
+  #
+  # This used to check "is the commit an ancestor of main" FIRST, which
+  # silently routed a dev-named tag to the main/PyPI pipeline whenever dev and
+  # main happened to be in sync (e.g. right after a merge) — the ancestor
+  # check won out over the "dev" in the tag name. Checking the name first
+  # fixes that, while still keeping the ancestor check as the guard for the
+  # non-dev path.
   detect-target:
     name: Detect release target
     runs-on: ubuntu-latest
@@ -23,33 +39,39 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: Check whether the tag commit is on main
+      - name: Check the release target
         id: check
         run: |
-          git fetch origin main
-          TAG_COMMIT="$(git rev-list -n 1 "${GITHUB_REF}")"
-          IS_ON_MAIN=$(git merge-base --is-ancestor "${TAG_COMMIT}" origin/main \
-                       && echo "true" || echo "false")
-          echo "is_main=${IS_ON_MAIN}" >> $GITHUB_OUTPUT
-
-          # Dev pre-release: a tag NOT on main whose name contains 'dev'
-          # (e.g. v1.3.1-dev0). Runs the full pipeline up to the TestPyPI install
-          # tests + a GitHub pre-release, then STOPS before the production PyPI
-          # publish. A tag off main WITHOUT 'dev' triggers nothing (should_run=false),
-          # so accidental/non-dev tags on dev never release.
           IS_DEV_RELEASE=false
-          if [ "${IS_ON_MAIN}" != "true" ] && [[ "${GITHUB_REF_NAME}" == *dev* ]]; then
+          if [[ "${GITHUB_REF_NAME}" == *dev* ]]; then
             IS_DEV_RELEASE=true
           fi
           echo "is_dev_release=${IS_DEV_RELEASE}" >> $GITHUB_OUTPUT
 
-          if [ "${IS_ON_MAIN}" = "true" ] || [ "${IS_DEV_RELEASE}" = "true" ]; then
+          # Only a non-dev-named tag needs the ancestor check at all -- a
+          # dev-named tag is never a main release, no matter where it sits.
+          IS_MAIN=false
+          if [ "${IS_DEV_RELEASE}" != "true" ]; then
+            git fetch origin main
+            TAG_COMMIT="$(git rev-list -n 1 "${GITHUB_REF}")"
+            if git merge-base --is-ancestor "${TAG_COMMIT}" origin/main; then
+              IS_MAIN=true
+            fi
+          fi
+          echo "is_main=${IS_MAIN}" >> $GITHUB_OUTPUT
+
+          if [ "${IS_DEV_RELEASE}" = "true" ] || [ "${IS_MAIN}" = "true" ]; then
             SHOULD_RUN=true
           else
             SHOULD_RUN=false
           fi
           echo "should_run=${SHOULD_RUN}" >> $GITHUB_OUTPUT
-          echo "Tag: ${GITHUB_REF_NAME}  commit: ${TAG_COMMIT}  on_main: ${IS_ON_MAIN}  dev_release: ${IS_DEV_RELEASE}  should_run: ${SHOULD_RUN}"
+
+          echo "Tag: ${GITHUB_REF_NAME}  is_main: ${IS_MAIN}  dev_release: ${IS_DEV_RELEASE}  should_run: ${SHOULD_RUN}"
+          if [ "${SHOULD_RUN}" != "true" ]; then
+            echo "::warning::Tag '${GITHUB_REF_NAME}' has no 'dev' in its name and its commit is not on main — skipping release entirely."
+          fi
+
 
   # ── Shared: run tests before any publish (main or dev pre-release) ────────
   test:
@@ -79,6 +101,7 @@ jobs:
           python -m pip install pytorch_lightning
           python -m unittest discover -s ./tests -p "test_*.py" -t . -v
 
+
   # ═══════════════════════════════════════════════════════════════════════════
   # DEV RELEASE — tag on dev branch, not yet merged to main
   # Publishes to TestPyPI and creates a GitHub pre-release.
@@ -86,7 +109,8 @@ jobs:
 
   build-and-publish-dev-release:
     name: Build & Publish Dev Release (TestPyPI)
-    needs: [detect-target,test]
+    # needs: [detect-target,test]
+    needs: [detect-target]
     runs-on: ubuntu-latest
     if: ${{ needs.detect-target.outputs.should_run == 'true' }}
     permissions:
@@ -102,6 +126,55 @@ jobs:
         with:
           python-version: '3.11'
 
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Build and vendor Weights Studio UI
+        env:
+          # weights_studio is a separate PRIVATE repo — the automatic
+          # secrets.GITHUB_TOKEN is scoped to THIS repo only and has no access
+          # to it, so the clone below must authenticate with a real
+          # cross-repo PAT instead.
+          WEIGHTS_STUDIO_TOKEN: ${{ secrets.WEIGHTS_STUDIO_API_TOKEN }}
+          IS_DEV_RELEASE: ${{ needs.detect-target.outputs.is_dev_release }}
+        run: |
+          set -euo pipefail
+
+          if [ -z "${WEIGHTS_STUDIO_TOKEN:-}" ]; then
+            echo "WEIGHTS_STUDIO_API_TOKEN secret is not set; cannot access the private weights_studio repo." >&2
+            exit 1
+          fi
+          CLONE_URL="https://x-access-token:${WEIGHTS_STUDIO_TOKEN}@github.com/GrayboxTech/weights_studio.git"
+
+          # Mirror the weightslab tag routing: a dev-named tag vendors the
+          # weights_studio "dev" branch; every other tag vendors main. No
+          # ls-remote probe -- it added a flaky network round-trip and a
+          # branch that's known to exist. This used to guess the ref from
+          # which weightslab branches happened to contain the tagged commit
+          # -- fragile, and NOT tied to is_dev_release, so it could silently
+          # vendor the wrong UI.
+          UI_REF="main"
+          if [ "${IS_DEV_RELEASE}" = "true" ]; then
+            UI_REF="dev"
+          fi
+          echo "Using weights_studio ref: ${UI_REF}"
+
+          rm -rf /tmp/weights_studio
+          git clone --depth 1 --branch "${UI_REF}" "${CLONE_URL}" /tmp/weights_studio
+
+          pushd /tmp/weights_studio >/dev/null
+          npm ci
+          npm test
+          npm run build
+          popd >/dev/null
+
+          rm -rf weightslab/ui/static
+          mkdir -p weightslab/ui/static
+          cp -R /tmp/weights_studio/dist/. weightslab/ui/static/
+
+          test -f weightslab/ui/static/index.html
+
       - name: Install build tools
         run: python -m pip install --upgrade pip build twine
 
@@ -456,6 +529,43 @@ jobs:
         with:
           python-version: '3.11'
 
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Build and vendor Weights Studio UI
+        env:
+          # weights_studio is a separate PRIVATE repo — the automatic
+          # secrets.GITHUB_TOKEN is scoped to THIS repo only and has no access
+          # to it, so the clone below must authenticate with a real
+          # cross-repo PAT instead.
+          WEIGHTS_STUDIO_TOKEN: ${{ secrets.WEIGHTS_STUDIO_API_TOKEN }}
+        run: |
+          set -euo pipefail
+
+          if [ -z "${WEIGHTS_STUDIO_TOKEN:-}" ]; then
+            echo "WEIGHTS_STUDIO_API_TOKEN secret is not set; cannot access the private weights_studio repo." >&2
+            exit 1
+          fi
+          CLONE_URL="https://x-access-token:${WEIGHTS_STUDIO_TOKEN}@github.com/GrayboxTech/weights_studio.git"
+          UI_REF="main"
+          echo "Using weights_studio ref: ${UI_REF}"
+
+          rm -rf /tmp/weights_studio
+          git clone --depth 1 --branch "${UI_REF}" "${CLONE_URL}" /tmp/weights_studio
+
+          pushd /tmp/weights_studio >/dev/null
+          npm ci
+          npm test
+          npm run build
+          popd >/dev/null
+
+          rm -rf weightslab/ui/static
+          mkdir -p weightslab/ui/static
+          cp -R /tmp/weights_studio/dist/. weightslab/ui/static/
+
+          test -f weightslab/ui/static/index.html
+
       - name: Install build tools
         run: python -m pip install --upgrade pip build twine
 

{weightslab-1.3.2 → weightslab-1.4.0}/.gitignore

@@ -3,19 +3,32 @@ weightslab.egg-info
 build
 agents
 
+# UI dirs — built SPA artifacts, regenerated by `npm run build` / build:embed;
+# never committed (the wheel embeds them at build time).
 dist
+static
+weightslab/ui/static/
+
+# Ignore files and directories generated by Python
 logs
 root_log_dir
 __pycache__
 venv
 runs
 data
+outputs
+!./tests/data/
+!./weightslab/data/
 MagicMock
+drop
+htmlcov
+htmlcov-report
 
 # Ignore hidden directories
 .history
 .lh
 .claude
+.coverage
 .chat
 .ai
 .pytest_cache

{weightslab-1.3.2 → weightslab-1.4.0}/AGENTS.md

@@ -59,11 +59,12 @@ experiment becomes inspectable/editable; Weights Studio is the UI for that.
 **Wire path (the thing that breaks most often):**
 
 ```
-Browser (Vite app)  →  Envoy :8080 (grpc-web ↔ grpc)  →  Python gRPC servicer  →  training loop
+Browser  →  weightslab start :8080 (grpc-web → grpc proxy)  →  Python gRPC servicer  →  training loop
 ```
 
-- The browser cannot speak raw gRPC, so **Envoy** transcodes grpc-web ↔ gRPC.
-  If Envoy is down or misconfigured, the UI loads but no data appears.
+- `weightslab start` is a pure-Python HTTP server that serves the bundled SPA
+  and translates grpc-web (browser) to raw gRPC (backend). No Docker, no Envoy.
+  If `weightslab start` is not running, the browser has no UI to load.
 - The gRPC servicer and the training loop run in the **same process, different
   threads**, coordinated by locks in
   `weightslab/weightslab/components/global_monitoring.py`.
@@ -88,13 +89,19 @@ wl.serve(serving_grpc=True, serving_cli=True)   # background threads, same proce
 wl.keep_serving()                                # keep the process alive for the UI
 ```
 
-Then start the studio stack (Envoy + frontend) and open it in a browser.
+Then start the UI in another terminal and open it in a browser:
+
+```bash
+weightslab start   # serves at http://localhost:8080 by default
+```
+
 Working starting points live in
 `weightslab/weightslab/examples/{PyTorch,Lightning,Usecases}/<usecase>/`
 (each is a `main.py` + `config.yaml`) — find the closest example and mirror it.
 
-Studio deployment details (Docker compose, Envoy, ports, certs) are in
-`weights_studio/docker/` and documented in `weightslab/docs/weights_studio.rst`.
+UI deployment details (port, TLS, certs) are documented in
+`weightslab/docs/weights_studio.rst`. TLS is opt-in: run `weightslab se` once,
+then `weightslab start --certs`.
 
 ---
 
@@ -138,10 +145,10 @@ ones when debugging:
 | Variable | Default | Why you touch it |
 |---|---|---|
 | `WEIGHTSLAB_LOG_LEVEL` | `INFO` | Set `DEBUG` to see what's happening. (`WATCHDOG` level sits between WARNING/ERROR.) |
-| `GRPC_BACKEND_HOST` / `GRPC_BACKEND_PORT` | `0.0.0.0` / `50051` | Backend must listen where Envoy expects it. |
-| `GRPC_TLS_ENABLED` | `1` | TLS on the gRPC socket. Set `0` **only** for isolated local debugging. |
-| `GRPC_TLS_REQUIRE_CLIENT_AUTH` | `1` | mTLS. Must match what Envoy presents. |
-| `GRPC_TLS_CERT_DIR` | `~/certs` | Where default cert files are looked up. |
+| `GRPC_BACKEND_HOST` / `GRPC_BACKEND_PORT` | `0.0.0.0` / `50051` | Backend gRPC bind address. |
+| `GRPC_TLS_ENABLED` | `0` | TLS on the gRPC socket. Set `1` with `weightslab start --certs`. |
+| `GRPC_TLS_REQUIRE_CLIENT_AUTH` | `0` | mTLS. Must match what `weightslab start --certs` presents. |
+| `WEIGHTSLAB_CERTS_DIR` | `~/.weightslab-certs` | Where cert files are looked up (single source of truth). |
 | `GRPC_AUTH_TOKEN` | *(unset)* | Optional metadata-token auth on top of mTLS. |
 | `GRPC_MAX_MESSAGE_BYTES` | `268435456` (256 MB) | Raise it if large tensors/image batches fail. |
 | `WEIGHTSLAB_DISABLE_WATCHDOGS` | `0` | Set `1` when debugging with breakpoints (see §5). |
@@ -151,7 +158,7 @@ ones when debugging:
 
 | Variable | Default | Why you touch it |
 |---|---|---|
-| `WS_SERVER_HOST` / `WS_SERVER_PORT` / `WS_SERVER_PROTOCOL` | `localhost` / `8080` / `https` | How the browser reaches the backend (via Envoy). The #1 connection-issue knob. |
+| `WS_SERVER_HOST` / `WS_SERVER_PORT` / `WS_SERVER_PROTOCOL` | `localhost` / `8080` / `http` | How the browser reaches the `weightslab start` server. The #1 connection-issue knob. |
 | `WS_HISTOGRAM_MAX_BINS` | `512` | Cap on metadata histogram bars. |
 | `BB_THUMB_RENDER` | `10` | Max bounding boxes drawn per **thumbnail**, per overlay (GT and PRED capped independently). |
 | `BB_MODAL_RENDER` | `100` | Max bounding boxes drawn per **modal** image, per overlay. A `?` button in the modal shows the active limit. |
@@ -161,11 +168,10 @@ ones when debugging:
 | `ENABLE_AGENT` | `1` | `0`/`false` removes the agent chat bar + history panel and stops the agent health poll. |
 
 > **VITE_ vs WS_/BB_/ENABLE_:** `VITE_*` variables are baked at **build time**
-> (changing them needs a rebuild). `WS_*` / `BB_*` / `ENABLE_*` are injected at
-> **container start** into `config.js` and read as `window.*` globals (the
-> toggles as `window.WS_ENABLE_*`) — changing them needs only a container restart
-> + browser reload (see the caching note in §5). Each `ENABLE_*` defaults to on;
-> set it to `0`/`false`/`no`/`off` to disable. Full reference:
+> (changing them needs a frontend rebuild). `WS_*` / `BB_*` / `ENABLE_*` are
+> injected into `config.js` at `weightslab start` time and read as `window.*`
+> globals — changing them needs only a restart + browser reload. Each `ENABLE_*`
+> defaults to on; set it to `0`/`false`/`no`/`off` to disable. Full reference:
 > `weightslab/docs/configuration.rst` (“Feature toggles”).
 
 ---
@@ -177,19 +183,15 @@ distilled from issues hit in development).
 
 **UI loads but the sample grid is empty / "failed to fetch" / gRPC errors.**
 The wire path (§1) is broken somewhere. Check in order: (1) backend actually
-serving on `0.0.0.0:50051`; (2) Envoy running and reachable on `:8080`;
-(3) frontend `WS_SERVER_HOST/PORT/PROTOCOL` point at Envoy, not the raw backend;
-(4) **TLS mismatch** — `WS_SERVER_PROTOCOL=https` vs `http`, Envoy server certs,
-and Envoy→backend mTLS certs all consistent. For local debugging you can drop
-TLS end-to-end (`GRPC_TLS_ENABLED=0` + `VITE_SERVER_PROTOCOL=http`).
+serving on `0.0.0.0:50051`; (2) `weightslab start` is running and the browser
+can reach it on `:8080`; (3) **TLS mismatch** if using `--certs` — run
+`weightslab se` first and export `WEIGHTSLAB_CERTS_DIR`. For local debugging
+drop TLS entirely (omit `--certs`; `GRPC_TLS_ENABLED=0`).
 
 **Changed an env var, restarted, but the UI still uses the old value.**
 - `VITE_*` is build-time → you must **rebuild** the frontend, not just restart.
-- `WS_*` / `BB_*` are read once per page load → you must **reload the tab**.
-- Historically `config.js` was served `Cache-Control: immutable` so even a
-  restart needed a **hard refresh**; current builds serve `/config.js` with
-  `no-store`, so a container restart + normal reload is enough. On an older
-  deployment, hard-refresh (Ctrl+Shift+R) or clear cache.
+- `WS_*` / `BB_*` / `ENABLE_*` are injected at `weightslab start` time → you
+  must **restart `weightslab start`** then reload the tab.
 
 **Sample grid flashes empty cells when auto-refresh fires.**
 An auto-refresh (timer or manual) that lands while a `GetDataSamples` grid fetch
@@ -247,7 +249,8 @@ OpenRouter** initialized from the UI via `/init` (then `/model` to switch,
 - `grid_data/` — grid + modal rendering (`GridCell.ts`, `DataImageService.ts`,
   `gridDataManager.ts`, `BboxRenderer.ts`, `SegmentationRenderer.ts`,
   `PointCloudViewer.ts`).
-- `docker/` — compose, `nginx-entrypoint.sh` (injects `config.js`), Envoy assets.
+- `ui/` — `server.py` (pure-Python HTTP + gRPC-Web proxy), `static/` (bundled SPA),
+  `utils/` (cert-generation scripts, sync-frontend helper).
 
 **Docs:** `weightslab/docs/` (Sphinx) — `configuration.rst` (all env vars),
 `weights_studio.rst` (studio deploy + agent), `quickstart.rst`, `grpc/`.
@@ -257,7 +260,7 @@ OpenRouter** initialized from the UI via `/init` (then `/model` to switch,
 ## 7. For contributors (working in a checkout)
 
 - **The two repos must sit side by side** (`…/weightslab`, `…/weights_studio`);
-  codegen and Envoy configs reach across by relative path.
+  proto codegen scripts reach across by relative path.
 - **Editing the proto is cross-repo** — do all of: edit
   `experiment_service.proto`; regenerate Python stubs from the repo root; run
   `npm run generate-proto:data` in weights_studio. Editing one side only leaves

weightslab-1.4.0/CHANGELOG.md

@@ -0,0 +1 @@
+# Changelog - 2026-07-23 v1.4.0 (0)

{weightslab-1.3.2/weightslab.egg-info → weightslab-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: weightslab
-Version: 1.3.2
+Version: 1.4.0
 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
@@ -13,9 +13,8 @@ Classifier: Programming Language :: Python :: 3.10
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: numpy<2.0,>=1.25.2; python_version < "3.13"
-Requires-Dist: numpy<3,>=2.1; python_version >= "3.13"
-Requires-Dist: pandas<3,>=2.2.3
+Requires-Dist: numpy<3,>=1.24
+Requires-Dist: pandas<3,>=2.2.2
 Requires-Dist: duckdb<2,>=1.1
 Requires-Dist: PyYAML<7,>=6.0.3
 Requires-Dist: dill<0.5,>=0.3.8
@@ -23,13 +22,11 @@ Requires-Dist: zstandard<1,>=0.22
 Requires-Dist: h5py<4,>=3.10
 Requires-Dist: xxhash<4.1,>=3.4
 Requires-Dist: tables<4,>=3.9
-Requires-Dist: torch<2.9,>=2.1; python_version < "3.13"
-Requires-Dist: torch==2.9; python_version >= "3.13"
-Requires-Dist: torchvision<0.24,>=0.16; python_version < "3.13"
-Requires-Dist: torchvision<1,>=0.24; python_version >= "3.13"
+Requires-Dist: torch<=2.9,>=2.1
+Requires-Dist: torchvision<1,>=0.16
 Requires-Dist: torchmetrics>=1.9
 Requires-Dist: grpcio<2,>=1.80
-Requires-Dist: protobuf<7,>=4.25
+Requires-Dist: protobuf<8,>=5.28.1
 Requires-Dist: pydantic<3,>=2.7
 Requires-Dist: Pillow<12,>=10
 Requires-Dist: graphviz<1,>=0.20
@@ -76,12 +73,14 @@ Dynamic: license-file
   <a href="https://github.com/GrayboxTech/weightslab/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License" /></a>
   <a href="https://github.com/GrayboxTech/weightslab/stargazers"><img src="https://img.shields.io/github/stars/GrayboxTech/weightslab?style=flat&color=5865F2" alt="Stars" /></a>
   <a href="https://pypi.org/project/weightslab/"><img src="https://img.shields.io/pypi/v/weightslab?style=flat&color=5865F2&logo=pypi&logoColor=white" alt="Version" /></a>
+  <a href="https://pepy.tech/project/weightslab"><img src="https://img.shields.io/pepy/dt/weightslab?style=flat&color=5865F2&logo=pypi&logoColor=white" alt="PyPI - Downloads" /></a>
+  <a href="https://github.com/GrayboxTech/weightslab/actions"><img src="https://img.shields.io/badge/CI-passing-brightgreen?style=flat&logo=githubactions&logoColor=white" alt="CI" /></a>
 </div>
 <br>
 
 ## What it does
 
-WeightsLab is an open-source PyTorch tool for dataset debugging, data quality monitoring, mislabel detection, and mid-training data curation for computer vision datasets: images, video & LiDAR point clouds. 
+WeightsLab is an open-source PyTorch tool for dataset debugging, data quality monitoring, mislabel detection, and mid-training data curation for computer vision datasets: images, video & LiDAR point clouds.
 Longer-term, we're building toward bringing dataset management, training, fine-tuning, and validation together in a single, unified workflow.
 
 <br>
@@ -92,24 +91,29 @@ Longer-term, we're building toward bringing dataset management, training, fine-t
 <br>
 Most data problems are invisible until your model tells you: through loss spikes, poor generalization, or silent underperformance. WeightsLab connects those training signals back to the exact samples causing them.
 
-**Wrap your training script with the SDK** to capture per-sample signals live.  
+**Wrap your training script with the SDK** to capture per-sample signals live.
 **Open Studio** to inspect, filter, and curate your dataset mid-training, without restarting.
 
-- **Detect** - Surface mislabels, outliers & class imbalance using live loss signals 
-- **Curate** - Discard bad samples, create data subsets, rebalance distributions 
-- **Continue** - Resume training on your cleaned dataset, no restart required 
+- **Detect** - Surface mislabels, outliers & class imbalance using live loss signals
+- **Curate** - Discard bad samples, create data subsets, rebalance distributions
+- **Continue** - Resume training on your cleaned dataset, no restart required
 <br>
 
-## Quickstart 
+## Quickstart
 
-![Python](https://img.shields.io/badge/Python-3.10--3.14-5865F2?style=flat&logo=python&logoColor=white)
-![Docker Desktop](https://img.shields.io/badge/Docker_Desktop-v4-0db7ed?style=flat&logo=docker&logoColor=white)
+![Python](https://img.shields.io/badge/Python-v3.10--v3.14-5865F2?style=flat&logo=python&logoColor=white)
 
 **1. Install**
 ```bash
 pip install weightslab
 ```
-**2. Wrap your training script**
+
+**2. Launch the Studio**
+```bash
+weightslab start
+```
+
+**3.a. Wrap your training script locally**
 ```python
 # wrap the objects in your training script
 
@@ -123,14 +127,14 @@ loader = wl.watch_or_edit(dataset, flag='data', loader_name="train")
 wl.serve(serving_grpc=True, serving_cli=False)
 ...
 ```
-**3. Launch Studio**
-```bash
-weightslab ui launch  # then open https://localhost:5173 🚀
-```
-<br>
 
-For a detailed installation guide and advanced configuration &rarr; [Installation Documentation](https://grayboxtech.github.io/weightslab/latest/quickstart.html).
+**3.b. Or in the cloud**
 
+[![Start coding with GCollab](https://img.shields.io/badge/Start_coding_with_GCollab-F9AB00?style=for-the-badge&logo=googlecolab&logoColor=white)](https://colab.research.google.com/github/GrayboxTech/weightslab/blob/main/weightslab/examples/Notebooks/Colab/wl-colab-quickstart.ipynb)
+
+
+<br>
+For a detailed installation guide and advanced configuration &rarr; [Installation Documentation](https://grayboxtech.github.io/weightslab/latest/quickstart.html).
 <br>
 
 > [!TIP]
@@ -141,8 +145,9 @@ For a detailed installation guide and advanced configuration &rarr; [Installatio
 > weightslab start example --seg      # segmentation
 > weightslab start example --det      # detection
 > weightslab start example --clus     # clustering
-> weightslab start example --gen      # generation
 > ```
+>
+> Explore our [sandbox](www.sandbox.graybx.com).
 
 <br>
 
@@ -162,22 +167,22 @@ For a detailed installation guide and advanced configuration &rarr; [Installatio
    parameters      = wl.watch_or_edit(parameters, flag='hp',     ...) # ← WeightsLab monitors your parameters and lets you update them from the UI
    model           = wl.watch_or_edit(model, flag='model', ...) # ← WeightsLab monitors your model state
    optimizer       = wl.watch_or_edit(optim.Adam(...),                         flag='opt',    ...) # ← Tracks optimizer state and lets you update the learning rate from the UI
-   
+
    train_criterion = wl.watch_or_edit(nn.CrossEntropyLoss(reduction="none"),  flag='signal', name="train_loss/sample", per_sample=True, log=True)   # ← Wrap and plot your signals on the UI
    test_criterion  = wl.watch_or_edit(nn.CrossEntropyLoss(reduction="none"),  flag='signal', name="test_loss/sample",  per_sample=True, log=False)  # ← Per-sample only, plot disabled
-   
+
    train_loader    = wl.watch_or_edit(train_dataset, flag='data', loader_name="train_loader", ...)  # ← Track your training dataset
    val_loader      = wl.watch_or_edit(val_dataset,   flag='data', loader_name="val_loader",   ...)  # ← Track your validation dataset
-   
+
 ```
 
 3. **Run your script, then launch the UI in a separate terminal:**
 ```bash
    python train.py
-   weightslab ui launch
+   weightslab start
 ```
 
-4. **Open your browser** `https://localhost:5173` and inspect your training in real time.
+4. **Open your browser** at the URL printed by `weightslab start` and inspect your training in real time.
 
 </details>
 
@@ -271,7 +276,7 @@ if __name__ == "__main__":
 
 ## WeightsLab vs Weights & Biases
 
-Weights & Biases (wandb) tracks experiments. WeightsLab connects training signals back to 
+Weights & Biases (wandb) tracks experiments. WeightsLab connects training signals back to
 the exact samples causing them — so you can fix your data, not just log it.
 
 <br>
@@ -373,9 +378,8 @@ Find our documentation [online](https://grayboxtech.github.io/weightslab/latest/
 
 New here (human or AI coding agent)? Start with [AGENTS.md](AGENTS.md) — it
 captures the cross-repo architecture (weightslab backend ↔ weights_studio
-frontend via the shared proto), the module maps, the `wl.watch_or_edit`
-integration pattern, where tests live, and the gotchas that aren't obvious from
-any single file. It's the fastest way to orient before a first change.
+frontend via the shared proto), the module maps, the integration pattern, where tests live, and the gotchas that aren't obvious from
+any single file. It's the fastest way to orient before a first change and contribution.
 
 </details>
 
@@ -384,7 +388,7 @@ any single file. It's the fastest way to orient before a first change.
 
 <br>
 
-We're building a community of ML engineers around data-centric training tooling. 
+We're building a community of ML engineers around data-centric training tooling.
 Interested in contributing or just want to say hi? → hello [at] graybx [dot] com
 
 </details>