weightslab 1.2.1__tar.gz → 1.2.2__tar.gz

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

@@ -133,13 +133,17 @@ jobs:
       - name: Install project dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install . --extra-index-url https://download.pytorch.org/whl/cpu
+          # Install the test extra so pytest, graphviz, torchmetrics,
+          # pytorch-lightning and tensorboard are available (several test modules
+          # import pytest / use pytest fixtures and cannot run under bare unittest).
+          python -m pip install '.[utest]' --extra-index-url https://download.pytorch.org/whl/cpu
+          python -m pip install pytest-timeout
 
       - name: Run unit tests - General
         run: |
           export WEIGHTSLAB_LOG_LEVEL="DEBUG"
-          python -m pip install pytorch_lightning
-          python -m unittest discover -s ./weightslab/tests -p "test_*.py" -t . -v
+          # A per-test timeout guards against any regression that hangs a test.
+          python -m pytest ./weightslab/tests -v --timeout=300
 
       # TODO (GP): WL CI do not find WS CI for now; token or visibility problem ??
       # - name: Trigger WeightsStudio CI

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

@@ -48,6 +48,7 @@ _version.py
 *.log
 *.csv
 *.sqlite
+*.txt
 *.db
 *.ipynb_checkpoints
 *.code-workspace
@@ -71,3 +72,5 @@ weightslab/ui/certs/*.srl
 # Ignore documentation build artifacts
 _build
 generated
+
+CLAUDE.md

weightslab-1.2.2/AGENTS.md

@@ -0,0 +1,209 @@
+# AGENTS.md — coding-agent & contributor onboarding
+
+This file is the shared context for **AI coding agents** (Claude Code, etc.) and
+**human contributors** working on WeightsLab. It captures the cross-repo
+architecture and the conventions that aren't obvious from any single file, so a
+newcomer (or an agent with no prior memory of the project) can orient quickly
+and debug confidently.
+
+> File/line references drift as the code evolves — treat them as starting
+> points and verify against the current source before relying on them.
+
+---
+
+## 1. Working with AI coding agents here
+
+WeightsLab is developed with coding agents in the loop. A few things make that
+productive and safe:
+
+- **This repo is one of three that ship together** (see §2). Many changes are
+  *cross-repo* — a proto edit touches the Python backend *and* the TypeScript
+  frontend. An agent that edits only one side leaves the build broken. Always
+  ask "does this change cross the proto boundary?"
+- **Keep changes additive and verify.** The default expectation is that
+  existing usecases keep working. Run the relevant test suites (§7) before
+  declaring done; prefer adding a new branch/flag over changing a shared path.
+- **Agent memory ≠ this file.** Agents may keep private, point-in-time "memory"
+  notes outside the repo. This file is the *committed, reviewed* distillation of
+  that knowledge — the part we want every contributor and every future agent to
+  start from. When you learn something load-bearing and non-obvious, add it
+  here (in a PR) rather than leaving it only in private memory.
+- **Onboarding flow:** read §2–§6 top to bottom, then skim §7–§8 before your
+  first change. For a feature, find the closest existing example in
+  `weightslab/weightslab/examples/` and mirror its structure.
+
+---
+
+## 2. The workspace: three repos, side by side
+
+These must be checked out as **sibling directories** — codegen and proxy
+configs reach across by relative path.
+
+| Repo | Role | Stack |
+|---|---|---|
+| **weightslab** (this repo) | Backend / core: training instrumentation, data ledger, gRPC service, the shared proto | Python |
+| **weights_studio** | Frontend: the studio UI that inspects/edits a running experiment | TypeScript + Vite |
+| **weightslab_kitchen** | Private examples / reference material | mixed |
+
+Layout assumption: `…/Codes/weightslab`, `…/Codes/weights_studio`,
+`…/Codes/weightslab_kitchen`.
+
+---
+
+## 3. Runtime integration (how backend ↔ frontend connect)
+
+One proto is the single source of truth:
+`weightslab/weightslab/proto/experiment_service.proto` (`service
+ExperimentService`, ~20 RPCs).
+
+- **Backend** implements it in `weightslab/trainer/services/experiment_service.py`
+  (servicer), delegating to `data_service.py`, `model_service.py`,
+  `agent_service.py`. The servicer and the in-process training loop run in the
+  **same process, different threads**, coordinated by the locks in
+  `weightslab/components/global_monitoring.py`.
+- **Frontend** consumes a generated TS client
+  (`weights_studio/src/experiment_service.client.ts`) produced by
+  `npm run generate-proto:data`, which runs `protoc` against the sibling
+  weightslab proto.
+- **Wire path:** browser → `:8080` Envoy (grpc-web ↔ grpc transcoding) → Python
+  gRPC servicer → training loop. The browser can't speak raw gRPC, so Envoy
+  translates.
+
+**Editing the proto is a three-step, cross-repo operation — do all three or the
+build breaks:**
+1. Edit `experiment_service.proto`.
+2. Regenerate Python stubs **from the repo root** (import style matters):
+   `python -m grpc_tools.protoc --proto_path=. --python_out=. --grpc_python_out=. weightslab/proto/experiment_service.proto`
+3. Regenerate the TS client in weights_studio: `npm run generate-proto:data`.
+
+---
+
+## 4. Backend module map (`weightslab/weightslab/`)
+
+Public API is re-exported from `__init__.py` (← `src.py`); users do
+`import weightslab as wl`.
+
+- **`src.py`** — the public verbs: `watch_or_edit`, `serve`, `keep_serving`,
+  `save_signals`, `tag_samples`, `query_*`, decorators (`eval_fn`,
+  `pointcloud_thumbnail`, `pointcloud_boxes`), etc.
+- **`trainer/`** — orchestration. `services/experiment_service.py` is the gRPC
+  servicer; `services/{model,data,agent}_service.py` are per-domain delegates;
+  `services/data_image_utils.py` handles preview/mask encoding.
+- **`components/`** — cross-cutting runtime: `global_monitoring.py`
+  (`guard_training_context` / `guard_testing_context`, pause controller, global
+  rlock), `checkpoint_manager.py`, `evaluation_controller.py`, `tracking.py`.
+- **`models/`** — `model_with_ops.py` (the watched/op-able model wrapper).
+- **`data/`** — the dataframe + storage backbone: `dataframe_manager.py`,
+  `data_samples_with_ops.py`, `sample_stats.py` (`SampleStatsEx`), `data_utils.py`,
+  `point_cloud_utils.py`; storage in `h5_dataframe_store.py`, `h5_array_store.py`,
+  `array_proxy.py`.
+- **`backend/`** — primitives: `ledgers.py` (`GLOBAL_LEDGER`, the watch/edit
+  substrate + hyperparameter registry), the watched-object interfaces, `logger.py`,
+  `audit_logger.py`, `cli.py`.
+- **`proto/`**, **`security/`** (`CertAuthManager`), **`ui/`** (bundled
+  Docker/Envoy assets), **`examples/`**.
+
+**Fan-in:** `ledgers.GLOBAL_LEDGER` is the hub — `watch_or_edit` registers
+objects there; the servicer reads/mutates through it.
+
+---
+
+## 5. Frontend module map (`weights_studio/src/`)
+
+Vite + TypeScript; entry `index.html` → `src/main.ts`.
+
+- **`main.ts`** — bootstrap: infers host/port (default `:8080`), builds the
+  grpc-web transport, wires panels and the sample modal.
+- **`experiment_service.client.ts` / `experiment_service.ts`** — generated
+  client/types (do **not** hand-edit; regenerate via `npm run generate-proto:data`).
+- **`grid_data/`** — sample grid + modal rendering (`GridCell.ts`,
+  `DataImageService.ts`, `BboxRenderer.ts`, `SegmentationRenderer.ts`,
+  `PointCloudViewer.ts` / `PointCloudService.ts`).
+- **`left_panel/`, `plots/`, `agent/`, `helpers.ts`, `ui/`, `utils/`** — controls,
+  Chart.js plots, the LLM agent panel, shared helpers/reconnection.
+- Tests in `tests/` (vitest unit + Playwright E2E).
+
+Build/proto scripts read the **sibling weightslab repo** at codegen time.
+
+---
+
+## 6. User-integration API (`import weightslab as wl`)
+
+How a user's own PyTorch script plugs in so the studio can inspect/edit it live.
+Examples: `weightslab/weightslab/examples/{PyTorch,Lightning,Usecases}/<usecase>/`
+(each a `main.py` + `config.yaml`).
+
+Wrap each training object with `wl.watch_or_edit(obj, flag=...)`; the returned
+tracked proxy is registered in the global ledger:
+- `flag="hyperparameters"` (dict), `flag="model"` (nn.Module, `device=…`),
+  `flag="optimizer"`, `flag="data"` (Dataset → tracked DataLoader: `loader_name`,
+  `batch_size`, `is_training`, `collate_fn`, …), `flag="loss"` (a
+  `reduction="none"` criterion; called with `(preds_raw, targets, batch_ids=ids,
+  preds=preds)`), `flag="metric"`.
+
+Conventions:
+- Wrap the train step in `with guard_training_context:` and eval in
+  `with guard_testing_context:` (from `weightslab.components.global_monitoring`)
+  — this is how pause/resume and train/test separation work.
+- Use `model.get_age()` (steps actually trained; survives checkpoint reloads),
+  not the raw loop counter.
+- `wl.serve(serving_grpc=…, serving_cli=…)` starts background serving threads in
+  the same process; end the script with `wl.keep_serving()`.
+- `task_type` on the dataset/model selects rendering: `classification`,
+  `segmentation`, `detection`, `detection_pointcloud`.
+
+---
+
+## 7. Tests & verification
+
+- **Backend (Python):** `python -m pytest weightslab/tests/...` — domains under
+  `tests/{data,trainer,gRPC,...}`.
+- **Frontend unit (vitest):** `npm run test` in weights_studio
+  (`tests/utests/**`).
+- **E2E / user-simulation (Playwright): lives in weights_studio, not here** —
+  the tests drive the real UI against a backend the harness spins up
+  (`test:realtime:*`, `test:e2e:*`).
+
+Before declaring a cross-repo change done: regenerate protos (both sides),
+build the frontend (`npm run build`), and run the affected unit suites.
+
+---
+
+## 8. Point-cloud detection pipeline (`detection_pointcloud`)
+
+A worked example of a non-trivial cross-repo feature; see
+`weightslab/weightslab/examples/Usecases/ws-3d-lidar-detection/` and
+`weightslab/weightslab/data/point_cloud_utils.py`.
+
+- **Task type** `detection_pointcloud` (covers 2D and 3D; box-row column count
+  decides dimensionality; legacy alias `detection_3d`).
+- **Dataset yields** `(cloud [M,F], uid, boxes, metadata)`. Cloud columns:
+  `x,y,z,intensity` (model reads the first 4) + optional viz-only channels
+  (`nx,ny,nz` normals, `r,g,b` colour) named via `point_feature_names`. Boxes:
+  3D `[cx,cy,cz,dx,dy,dz,yaw,cls?,conf?]` or 2D `[cx,cy,dx,dy,cls?,conf?]`;
+  predictions use the **same** schema.
+- **Previews** (thumbnail/grid/modal image) are **server-rendered 2D** (BEV or
+  range projection) with boxes projected on; the raw cloud streams to the
+  browser only for the interactive **three.js 3D viewer** (modal "3D" toggle),
+  via the `GetPointCloud` streaming RPC. Colour modes are data-driven (height /
+  distance / intensity / camera-RGB / normal shading).
+- **Override hooks:** dataset methods `render_thumbnail_2d` / `project_boxes_2d`,
+  or global decorators `@wl.pointcloud_thumbnail` / `@wl.pointcloud_boxes`.
+- **Real data:** `source: kitti_raw` downloads a KITTI raw drive (sync +
+  tracklets for GT boxes + calibration for RGB) to a temp dir; falls back to
+  synthetic scenes offline.
+
+---
+
+## 9. Contributor checklist & gotchas
+
+- Proto change → regen Python (from repo root) **and** TS, or runtime breaks.
+- The three repos must sit side by side; codegen uses relative paths.
+- Training + serving share a process — respect the `global_monitoring` locks and
+  the `guard_*` context managers.
+- TLS/auth in the bundled UI is decided by the presence of certs under
+  `WEIGHTSLAB_CERTS_DIR` (single source of truth) — don't hardcode secure/insecure.
+- Per-instance data (detection/segmentation) uses a MultiIndex
+  `(sample_id, annotation_id)` through the dataframe and H5 store.
+- Playwright/E2E tests belong in weights_studio, not here.
+- Don't commit large datasets; real-data downloads go to a temp dir.

weightslab-1.2.2/CHANGELOG.md

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: weightslab
-Version: 1.2.1
+Version: 1.2.2
 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
@@ -26,6 +26,7 @@ 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: torchmetrics>=1.9
 Requires-Dist: grpcio<2,>=1.80
 Requires-Dist: protobuf<7,>=4.25
 Requires-Dist: pydantic<3,>=2.7
@@ -112,40 +113,117 @@ The granular statistics and interactive paradigm enable powerful workflows:
   * Iterative pruning or growing of the architectures (INCOMING feature)
 
 
-## Find our demos:
-The password is **graybx**. More demo to come in the future!
+## Quick Start
 
-  <a href="https://preview.graybx.com/">
-    <p style="text-indent:20px;">DEMOS</p>
-  </a>
+### Requirements
+
+- **Docker Desktop v4.77 or newer** — required to deploy the Weights Studio UI (`weightslab ui launch`).
+- **Docker Compose v2** (the `docker compose` CLI plugin, bundled with Docker Desktop) — *recommended*. The legacy v1 standalone binary (`docker-compose`, **≥ 1.27**) also works: `weightslab ui launch` auto-detects whichever is installed and uses it. Compose v1 below 1.27 is **not** supported.
+- **Python >=3.10, <3.15** — to install and run the `weightslab` framework.
+> [!OPTIONAL]
+> We are fully compatible with Conda.
+
+> [!TIP]
+> Check your Compose version with `docker compose version` (v2) or `docker-compose --version` (v1). If `docker compose version` prints a version string, you have v2.
 
 
-## Getting Started
 ### Installation
 
-Define a Python environment (Python >=3.10, <3.15)
+> [!OPTIONAL]
+> Seting a clean environment:
+> Define a Python environment:
 ```bash
 python -m venv weightslab_venv
 ./weightslab_venv/Scripts/activate
 ```
-Or install directly on your machine.
+> Or install directly on your machine.
 
 Install our framework:
 ```bash
 pip install weightslab
 ```
 
-Deploy our interface with Docker:
+Deploy our interface:
 ```bash
 weightslab ui launch
 ```
 
+`weightslab ui launch` removes any stale weightslab/weights_studio Docker resources that could break the launch, then starts the UI stack. **By default it runs unsecured (HTTP, no gRPC auth) — no certificates are generated.**
+
+To run secured (HTTPS + gRPC auth), pass `--certs`:
+```bash
+weightslab ui launch --certs   # generates TLS certs + a gRPC auth token if missing, then launches secured
+```
+
+> [!IMPORTANT]
+> When using certs, set `WEIGHTSLAB_CERTS_DIR` so the training backend and any new terminal use the **same** certificates (it is the single source of truth). `weightslab se` and `weightslab ui launch --certs` print the exact export/`setx` command for your shell. You can also generate certs up front with `weightslab se`.
+<!--
+Want to see it working end to end without writing any code? Start a bundled demo (it installs the example's requirements first — no prompts — then trains and serves until you stop it with `Ctrl+C`). It defaults to classification; pick another with a flag:
+```bash
+weightslab start example          # classification (default)
+weightslab start example --cls    # classification
+weightslab start example --seg    # segmentation
+weightslab start example --det    # detection
+weightslab start example --clus   # clustering
+weightslab start example --gen    # generation
+``` -->
+<!-- Then run `weightslab ui launch` in another terminal and open `https://localhost:5173`. -->
+
+<!-- Run `weightslab`, `weightslab help`, or `weightslab -h` at any time to see the banner and the full command reference. -->
+
 > [!IMPORTANT]
 > For a detailed installation guide and more advanced features, please see the [Installation Documentation](https://grayboxtech.github.io/weightslab/latest/quickstart.html).
 
 
 ## Quick Training Example
 
+### Step-by-Step Integration
+
+1. **Add the import** at the top of your script:
+   ```python
+   import weightslab as wl  # ← Include our SDK into your experiment
+   ```
+
+2. **Wrap your parameters** with WeightsLab tracking:
+   ```python
+   model = wl.watch_or_edit(parameters, ...)  # ← Now WeightsLab monitors your parameters and allow you to update them from your UI
+   ```
+
+3. **Wrap your model** with WeightsLab tracking:
+   ```python
+   model = wl.watch_or_edit(SimpleModel(...), ...)  # ← Now WeightsLab monitors your model state
+   ```
+
+4. **Wrap your optimizer** with WeightsLab tracking:
+   ```python
+   optimizer = wl.watch_or_edit(optim.Adam(...), ...)  # ← Tracks optimizer state and update optimizer learning rate from your UI
+   ```
+
+5. **Wrap your signal** with WeightsLab tracking:
+   ```python
+    criterion = wl.watch_or_edit(nn.CrossEntropyLoss(reduction="none"), ...)  # ← Tracks this signal and others (metrics, ..etc) from your UI
+   ```
+
+6. **Wrap your dataset** with WeightsLab tracking:
+   ```python
+    train_loader = wl.watch_or_edit(dataset, ...)  # ← Tracks this dataset and others (validation, test) from your UI
+   ```
+
+7. **Run your training script** as usual:
+   ```bash
+   python train.py
+   ```
+
+8. **Launch the UI** in another terminal:
+   ```bash
+   weightslab ui launch
+   ```
+
+9. **Open your browser** to `https://localhost:5173` to track experiment evoluation and results!
+
+
+### Details
+
 <details>
 <summary><b>Here's a complete example showing how to integrate WeightsLab into a basic PyTorch training script:</b></summary>
 
@@ -158,7 +236,7 @@ import torch
 import torch.nn as nn
 import torch.optim as optim
 from torch.utils.data import DataLoader, TensorDataset
-import weightslab as wl  # ← Import WeightsLab (auto-creates secure certs!)
+import weightslab as wl  # ← Import WeightsLab (uses TLS certs from WEIGHTSLAB_CERTS_DIR if present)
 
 
 # Define a simple model
@@ -234,7 +312,7 @@ def main():
 
     # Training loop
     print("🏃 Starting training...")
-    print("💡 Launch the UI with: weightslab ui docker launch")
+    print("💡 Launch the UI with: weightslab ui launch")
     print("🌐 Open browser to: https://localhost:5173")
     n_epochs = parameters.get('n_epochs')
     pbar = tqdm.tqdm(range(n_epochs), desc='Training..') if parameters.get('tqdm_display', False) else range(n_epochs)
@@ -360,207 +438,34 @@ if __name__ == "__main__":
 </details>
 
 
-### Step-by-Step Integration
-
-1. **Add the import** at the top of your script:
-   ```python
-   import weightslab as wl  # ← Include our SDK into your experiment
-   ```
-
-2. **Wrap your parameters** with WeightsLab tracking:
-   ```python
-   model = wl.watch_or_edit(parameters, ...)  # ← Now WeightsLab monitors your parameters and allow you to update them from your UI
-   ```
-
-3. **Wrap your model** with WeightsLab tracking:
-   ```python
-   model = wl.watch_or_edit(SimpleModel(...), ...)  # ← Now WeightsLab monitors your model state
-   ```
-
-4. **Wrap your optimizer** with WeightsLab tracking:
-   ```python
-   optimizer = wl.watch_or_edit(optim.Adam(...), ...)  # ← Tracks optimizer state and update optimizer learning rate from your UI
-   ```
-
-5. **Wrap your signal** with WeightsLab tracking:
-   ```python
-    criterion = wl.watch_or_edit(nn.CrossEntropyLoss(reduction="none"), ...)  # ← Tracks this signal and others (metrics, ..etc) from your UI
-   ```
-
-6. **Wrap your dataset** with WeightsLab tracking:
-   ```python
-    train_loader = wl.watch_or_edit(dataset, ...)  # ← Tracks this dataset and others (validation, test) from your UI
-   ```
-
-7. **Run your training script** as usual:
-   ```bash
-   python train.py
-   ```
-
-8. **Launch the UI** in another terminal:
-   ```bash
-   weightslab ui docker launch
-   ```
-
-9. **Open your browser** to `https://localhost:5173` to track experiment evoluation and results!
-
 
 ### What WeightsLab Does Automatically
 
-- 🔐 **Creates TLS certificates** in `~/.weightslab-certs/`
-- 🎫 **Generates secure auth tokens** for gRPC communication
-- 📊 **Tracks model parameters** and optimizer state in real-time
+<!-- - 📊 **Tracks model parameters** and optimizer state in real-time -->
+<!-- - 🔄 **Enables model editing (incoming feature)** and hyperparameter tuning through the UI -->
+- 📊 **Experiment tracking for reproducibility**
 - 📈 **Provides live metrics** and visualization in the web UI
-- 🔄 **Enables model editing (incoming feature)** and hyperparameter tuning through the UI
-
-
-## Security
-
-By default, WeightsLab runs in **unsecured mode** (NO TLS, HTTP, no gRPC authentification). To enable TLS encryption and gRPC authentication:
-
-### Quick Setup + Launch
-Setup secure environment AND launch Docker in one command:
-```bash
-weightslab ui docker se
-export WEIGHTSLAB_CERTS_DIR='~/.weightslab-certs/'  # Windows commands is
-```
-
-This will:
-1. Generate TLS certificates and gRPC auth token in `~/.weightslab-certs/`
-2. Launch the Docker stack with security enabled
-3. If setup fails, Docker still launches (unsecured fallback)
-
-### Separate Steps (If Needed)
-Setup secure environment only:
-```bash
-weightslab se
-
-# Ubuntu command
-echo 'export WEIGHTSLAB_CERTS_DIR="~/.weightslab-certs/"' >> ~/.bashrc
-source ~/.bashrc
-
-# Windows command
-# setx WEIGHTSLAB_CERTS_DIR '~/.weightslab-certs/' /M
-```
-
-Then launch Docker later:
-```bash
-weightslab ui docker launch
-```
-
-### Custom Certificates Directory
-Store certificates in a custom location using the `WEIGHTSLAB_CERTS_DIR` environment variable:
-```bash
-# Generate the certs
-weightslab se "/path/to/my/certs"
-
-# Export path to env.
-# Ubuntu command
-echo 'export WEIGHTSLAB_CERTS_DIR=/path/to/my/certs' >> ~/.bashrc
-source ~/.bashrc
-
-# Windows command
-# setx WEIGHTSLAB_CERTS_DIR /path/to/my/certs /M
+- 🔄 **Enables data supervision during training** and experiment hyperparameter tuning through the UI
 
-# Start UI
-weightslab ui docker launch
-```
-
-### Options for Secure Environment Setup
-
-**For `weightslab se` or `weightslab ui docker se`:**
-
-| Flag | Effect |
-|---|---|
-| `--force-certs` | Regenerate certificates even if they already exist |
-| `--no-auth` | Skip gRPC auth token generation (TLS only) |
-
-**Examples:**
-```bash
-weightslab se --force-certs              # Regenerate certs only
-weightslab se --no-auth                  # TLS only, no gRPC token
-weightslab ui docker se                  # Setup + launch in one
-weightslab ui docker se --force-certs    # Setup (regenerate) + launch
-```
-
-### What Gets Created?
-After running `weightslab se` or `weightslab ui docker se`, your `~/.weightslab-certs/` directory contains:
-- `backend-server.crt` — Backend TLS certificate
-- `backend-server.key` — Backend TLS private key
-- `ca.crt` — CA certificate
-- `.grpc_auth_token` — gRPC authentication token (if not using `--no-auth`)
-
-### Running Without Security
-To explicitly run in unsecured mode, delete the certificates directory:
-```bash
-rm -r ~/.weightslab-certs
-weightslab ui docker launch  # Falls back to unsecured HTTP
-```
 
-### Testing the Setup
-**Secured environment:**
-```bash
-weightslab se                      # Setup certs and token
-weightslab ui docker launch        # Launch Docker
-python main.py                     # Backend finds certs, runs secured
-```
+## Examples
 
-**Unsecured environment:**
+### Local examples
+After starting the UI, launch a local experiment with the command:
 ```bash
-weightslab ui docker launch        # Launch Docker (no certs)
-python main.py                     # Backend runs unsecured
+weightslab start example          # classification (default)
+# weightslab start example --cls    # classification
+# weightslab start example --seg    # segmentation
+# weightslab start example --det    # detection
+# weightslab start example --clus   # clustering
+# weightslab start example --gen    # generation
 ```
 
-
-## Cookbook
-
-Check out our materials, which include examples ranging from toys to more complex models and experiments.
-
-Quickstart examples:
-- [WeightsLab - Classification toy (PyTorch)](https://github.com/GrayboxTech/weightslab/tree/main/weightslab/examples/PyTorch/ws-classification)
-- [WeightsLab - Segmentation toy (PyTorch)](https://github.com/GrayboxTech/weightslab/tree/main/weightslab/examples/PyTorch/ws-segmentation)
-- [WeightsLab - Detection toy (PyTorch)](https://github.com/GrayboxTech/weightslab/tree/main/weightslab/examples/PyTorch/ws-detection)
-- [WeightsLab - Classification toy (PyTorch Lightning)](https://github.com/GrayboxTech/weightslab/tree/main/weightslab/examples/PyTorch_Lightning/ws-classification)
-
-
-## Configuration
-
-WeightsLab and Weightslab UI are configured through environment variables.
-A fully commented .env template is included at the repository root — copy it and adjust for your setup:
-
-```bash
-cp .env .env.local   # or edit .env directly
-```
-
-| Category | Key variables |
-|---|---|
-| **Logging** | `WEIGHTSLAB_LOG_LEVEL`, `WEIGHTSLAB_LOG_TO_FILE`, `WEIGHTSLAB_ROOT_LOG_DIR` |
-| **gRPC server** | `GRPC_BACKEND_HOST`, `GRPC_BACKEND_PORT`, `GRPC_MAX_MESSAGE_BYTES`, `GRPC_TLS_ENABLED`, `GRPC_TLS_CERT_DIR`, `GRPC_TLS_CERT_FILE`, `GRPC_TLS_KEY_FILE`, `GRPC_TLS_CA_FILE`, `GRPC_TLS_REQUIRE_CLIENT_AUTH`, `GRPC_AUTH_TOKEN`, `GRPC_AUTH_TOKENS` |
-| **Watchdog** | `GRPC_WATCHDOG_STUCK_SECONDS`, `GRPC_WATCHDOG_INTERVAL_SECONDS`, `GRPC_WATCHDOG_RESTART_THRESHOLD`, `GRPC_WATCHDOG_EXIT_ON_STUCK` |
-| **Data / cache** | `WL_MAX_PREVIEW_CACHE_SIZE`, `WL_PREVIEW_CACHE_WARMUP_WAIT_MS`, `WL_DEFAULT_THUMBNAIL_SIZE`, `WL_INSTANCE_AGGREGATION`, `WEIGHTSLAB_SAVE_PREDICTIONS_IN_H5` |
-| **AI keys** | `OPENROUTER_API_KEY` |
-| **Agent config** | `AGENT_CONFIG_PATH` |
-| **Weightslab UI** | `VITE_SERVER_HOST`, `VITE_SERVER_PORT`, `VITE_HISTOGRAM_MAX_BINS`, `ENVOY_HOST`, `ENVOY_PORT` |
-
-`AGENT_CONFIG_PATH` lets you point the data agent to a custom directory that contains `agent_config.yaml`.
-If set, WeightsLab looks for `<AGENT_CONFIG_PATH>/agent_config.yaml` before fallback locations.
-
-WeightsLab also reads TLS settings from registered runtime config (hyperparameters),
-using config-first precedence over environment variables.
-
-If TLS is enabled (`grpc_tls_enabled` in config or `GRPC_TLS_ENABLED` in env),
-certificate path resolution is:
-1. config file paths (`grpc_tls_cert_file`, `grpc_tls_key_file`, `grpc_tls_ca_file`)
-2. env file paths (`GRPC_TLS_CERT_FILE`, `GRPC_TLS_KEY_FILE`, `GRPC_TLS_CA_FILE`)
-3. config directory (`grpc_tls_cert_dir`)
-4. env directory (`GRPC_TLS_CERT_DIR`)
-5. default `~/certs` (`backend-server.crt`, `backend-server.key`, `ca.crt`)
-
-TLS flags also follow config-first precedence:
-`grpc_tls_enabled` then `GRPC_TLS_ENABLED`, and
-`grpc_tls_require_client_auth` then `GRPC_TLS_REQUIRE_CLIENT_AUTH`.
-
-> Full documentation with all variables and their descriptions: [docs/configuration.rst](docs/configuration.rst)
+###  Cloud examples
+Find our demos online. The password is **graybx**.
+<a href="https://preview.graybx.com/">
+  <p style="text-indent:20px;">DEMOS</p>
+</a>
 
 
 ## AI Agent
@@ -575,9 +480,10 @@ Use OpenRouter when you want larger hosted models and model selection directly f
 
 
 ### Cloud OpenRouter
-#### SDK Configuration
 You can either preconfigure OpenRouter in `agent_config.yaml` / `.env`, or initialize it interactively from Weightslab UI.
 
+#### SDK Configuration
+
 Example static configuration:
 
 ```yaml
@@ -606,16 +512,6 @@ OpenRouter models can be initialized and set directly from the UI:
 
 The default OpenRouter model, as recommended by Graybx, is `meta-llama/llama-3.3-70b-instruct`.
 
-### Agent Commands in Weightslab UI
-
-The agent input supports these commands:
-
-- `/init` initializes the cloud provider flow for OpenRouter
-- `/model` opens the model chooser and switches the active OpenRouter model
-- `/reset` clears the current runtime agent connection and status
-
-The agent history also records setup and model-change events as log-style entries, separate from normal agent responses.
-
 ### Typical Usage Flow
 
 1. Start your WeightsLab backend (e.g., "main.py").
@@ -629,11 +525,16 @@ The agent history also records setup and model-change events as log-style entrie
 
 ## Documentation (API + SDK)
 
-* <div>
-  <a href="https://grayboxtech.github.io/weightslab/latest/index.html">
-    <p>Documentation</p>
-  </a>
-</div>
+Find our documentation [online](https://grayboxtech.github.io/weightslab/latest/index.html).
+
+
+## Contributing & onboarding
+
+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.
 
 
 ## Community