weightslab 1.2.5__tar.gz → 1.3.0__tar.gz

{weightslab-1.2.5 → weightslab-1.3.0}/.github/workflows/ci.yml

@@ -2,19 +2,52 @@ name: Code CI
 
 on:
   push:
-    branches: [ main, dev ]
+    # Fire on every branch so the `gate` job below can decide whether to run.
+    # GitHub cannot filter on commit message at the event level, so we trigger
+    # broadly and gate execution: main/dev always run, other branches run only
+    # when the head commit message contains "[force ci]".
+    branches: [ '**' ]
     tags: [ 'v*' ]
   pull_request:
-    types: [ opened, reopened, ready_for_review ]
+    types: [ opened, reopened, ready_for_review, synchronize ]
   workflow_dispatch:
 
 jobs:
-  # Required gate: a lint violation here FAILS the CI run. This job has no
-  # `needs` and nothing `needs` it, so it runs in parallel with install/test/
-  # build — its failure turns the run red but does NOT stop the other jobs from
-  # running (GitHub Actions does not cancel sibling jobs on failure).
+  # Single source of truth for "should the core CI jobs run?". Reproduces the
+  # previous trigger rules (PR / manual dispatch / main / dev run; tags skip)
+  # and adds a manual escape hatch for custom branches via "[force ci]".
+  gate:
+    runs-on: ubuntu-latest
+    outputs:
+      run_ci: ${{ steps.decide.outputs.run_ci }}
+    steps:
+      - name: Decide whether to run CI
+        id: decide
+        env:
+          # Evaluated by GitHub (not the shell) so the raw commit message is
+          # never interpolated into bash — avoids quoting/injection issues.
+          FORCE_CI: ${{ contains(github.event.head_commit.message, '[force ci]') }}
+        run: |
+          if [ "${{ github.event_name }}" != "push" ]; then
+            run_ci=true            # PRs and manual dispatch always run
+          elif [[ "${{ github.ref }}" == refs/tags/* ]]; then
+            run_ci=false           # tag pushes are handled by the release workflow
+          elif [ "${{ github.ref }}" = "refs/heads/main" ] || [ "${{ github.ref }}" = "refs/heads/dev" ] || [[ "${{ github.ref }}" == refs/heads/v* ]]; then
+            run_ci=true            # default branches and release branches (v*) always run
+          elif [ "${FORCE_CI}" = "true" ]; then
+            run_ci=true            # custom branch opted in via [force ci]
+          else
+            run_ci=false           # custom branch without [force ci] → skip
+          fi
+          echo "run_ci=${run_ci}" >> "$GITHUB_OUTPUT"
+          echo "Decision: run_ci=${run_ci} (event=${{ github.event_name }}, ref=${{ github.ref }}, force_ci=${FORCE_CI})"
+  # Required gate: a lint violation here FAILS the CI run. Nothing `needs` this
+  # job, so it runs in parallel with install/test/build — its failure turns the
+  # run red but does NOT stop the other jobs from running (GitHub Actions does
+  # not cancel sibling jobs on failure).
   code-quality:
-    if: ${{ github.event_name != 'push' || !startsWith(github.ref, 'refs/tags/') }}
+    needs: gate
+    if: ${{ needs.gate.outputs.run_ci == 'true' }}
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
@@ -24,7 +57,7 @@ jobs:
 
       - name: Set up Python
         id: setup-python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.11'
 
@@ -99,7 +132,8 @@ jobs:
   # 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/') }}
+    needs: gate
+    if: ${{ needs.gate.outputs.run_ci == 'true' }}
     runs-on: ubuntu-latest
     name: install (Python 3.11)
     steps:
@@ -107,7 +141,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Set up Python 3.11
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.11'
 
@@ -145,7 +179,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
           allow-prereleases: ${{ matrix.allow-prereleases || false }}
@@ -160,16 +194,17 @@ jobs:
           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/') }}
+    if: ${{ needs.gate.outputs.run_ci == 'true' }}
     runs-on: ubuntu-latest
-    # Depends on the fast 3.11 gate only — the matrix runs independently in parallel.
-    needs: install
+    # Depends on the fast 3.11 install gate; `gate` is also a direct need so this
+    # job can read run_ci (the matrix and main-only jobs run independently).
+    needs: [ gate, install ]
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.11'
 
@@ -188,25 +223,6 @@ jobs:
           # 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
-      #   env:
-      #     WS_TOKEN: ${{ secrets.WEIGHTS_STUDIO_API_TOKEN }}
-      #   run: |
-      #     if [ -z "${WS_TOKEN}" ]; then
-      #       echo "WEIGHTS_STUDIO_API_TOKEN not set; skipping WeightsStudio trigger."
-      #       exit 0
-      #     fi
-
-      #     # Trigger the ws-ci workflow in the weights_studio repository on main.
-      #     curl -fSs -X POST "https://api.github.com/repos/GrayboxTech/weights_studio/actions/workflows/ws-ci.yml/dispatches" \
-      #       -H "Authorization: Bearer ${WS_TOKEN}" \
-      #       -H "Accept: application/vnd.github+json" \
-      #       -H "Content-Type: application/json" \
-      #       -d '{"ref":"main"}'
-
-      #     echo "WeightsStudio workflow dispatch requested successfully."
-
   build-and-publish-dev:
     # 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' }}
@@ -224,7 +240,7 @@ jobs:
           fetch-depth: 0
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.11'
 
@@ -316,7 +332,7 @@ jobs:
       contents: read
     steps:
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
           allow-prereleases: ${{ matrix.allow-prereleases || false }}

{weightslab-1.2.5 → weightslab-1.3.0}/.github/workflows/release.yml

@@ -40,20 +40,25 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: '3.11'
 
       - name: Install 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 tests
         run: |
           export WEIGHTSLAB_LOG_LEVEL="DEBUG"
           python -m pip install pytorch_lightning
-          python -m unittest discover -s ./weightslab/tests -p "test_*.py" -t . -v
+          # python -m unittest discover -s ./weightslab/tests -p "test_*.py" -t . -v
+          python -m pytest ./weightslab/tests -v --timeout=300
 
   # ═══════════════════════════════════════════════════════════════════════════
   # DEV RELEASE — tag on dev branch, not yet merged to main
@@ -74,7 +79,7 @@ jobs:
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: '3.11'
 
@@ -108,7 +113,7 @@ jobs:
           python -m twine upload --repository-url https://test.pypi.org/legacy/ --verbose dist/*
 
       - name: Upload build artifacts for release
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: dev-release-dist
           path: dist/
@@ -133,7 +138,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
           allow-prereleases: ${{ matrix.allow-prereleases || false }}
@@ -195,7 +200,7 @@ jobs:
           fetch-depth: 0
 
       - name: Download build artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v7
         with:
           name: dev-release-dist
           path: dist/
@@ -226,7 +231,7 @@ jobs:
 
           export PRS_JSON
           PRS_JSON=$(gh pr list --state merged --base "dev" --limit 100 \
-            --json number,title,mergedAt,url,author,body \
+            --json number,title,mergedAt,url,author,body,commits \
             2>/dev/null || echo "[]")
 
           python3 << 'PYEOF'
@@ -249,6 +254,29 @@ jobs:
               line += f"\n\n  > {desc}"
             return line
           filtered = [pr for pr in prs_data if pr.get("mergedAt", "") > prev_date]
+          # "What's Changed precisely": list each merged PR's own developer commits,
+          # NOT the squashed/merge/chore commits that land on the release branch
+          # (those are redundant with the PR list above and not useful).
+          _seen_commits = set()
+          _commit_blocks = []
+          for pr in filtered:
+            _commit_lines = []
+            for c in (pr.get("commits") or []):
+              oid = (c.get("oid") or "")[:7]
+              head = (c.get("messageHeadline") or "").strip()
+              if not head or head.startswith("Merge "):
+                continue
+              key = (oid, head)
+              if key in _seen_commits:
+                continue
+              _seen_commits.add(key)
+              _commit_lines.append(f"  - `{oid}` {head}")
+            if _commit_lines:
+              _commit_blocks.append(
+                f"**[#{pr['number']}]({pr['url']}) {pr['title']}**\n" + "\n".join(_commit_lines)
+              )
+          # Fall back to the raw git log only when no PR commits are available.
+          commits_section = "\n\n".join(_commit_blocks) if _commit_blocks else commits
           if filtered:
             prs_lines = "\n".join(_pr_entry(pr) for pr in filtered)
             seen, clabels = set(), []
@@ -276,7 +304,7 @@ jobs:
             "Happy Training!\n\n"
             "---\n\n"
             "### What's Changed precisely:\n\n"
-            f"{commits}\n\n"
+            f"{commits_section}\n\n"
             "---\n\n"
             "### Thank you!\n\n"
             f"{contributors}\n"
@@ -303,7 +331,8 @@ jobs:
 
   build-and-publish-main:
     name: Build & Publish Main (PyPI)
-    needs: [detect-target]
+    needs: [detect-target,test]
+    # needs: [detect-target]
     runs-on: ubuntu-latest
     if: ${{ needs.detect-target.outputs.is_main == 'true' }}
     permissions:
@@ -315,7 +344,7 @@ jobs:
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: '3.11'
 
@@ -349,7 +378,7 @@ jobs:
           python -m twine upload dist/* --non-interactive --verbose
 
       - name: Upload build artifacts for release
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: main-release-dist
           path: dist/
@@ -367,7 +396,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -427,7 +456,7 @@ jobs:
           fetch-depth: 0
 
       - name: Download build artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v7
         with:
           name: main-release-dist
           path: dist/
@@ -458,7 +487,7 @@ jobs:
 
           export PRS_JSON
           PRS_JSON=$(gh pr list --state merged --base "main" --limit 100 \
-            --json number,title,mergedAt,url,author,body \
+            --json number,title,mergedAt,url,author,body,commits \
             2>/dev/null || echo "[]")
 
           python3 << 'PYEOF'
@@ -481,6 +510,29 @@ jobs:
               line += f"\n\n  > {desc}"
             return line
           filtered = [pr for pr in prs_data if pr.get("mergedAt", "") > prev_date]
+          # "What's Changed precisely": list each merged PR's own developer commits,
+          # NOT the squashed/merge/chore commits that land on the release branch
+          # (those are redundant with the PR list above and not useful).
+          _seen_commits = set()
+          _commit_blocks = []
+          for pr in filtered:
+            _commit_lines = []
+            for c in (pr.get("commits") or []):
+              oid = (c.get("oid") or "")[:7]
+              head = (c.get("messageHeadline") or "").strip()
+              if not head or head.startswith("Merge "):
+                continue
+              key = (oid, head)
+              if key in _seen_commits:
+                continue
+              _seen_commits.add(key)
+              _commit_lines.append(f"  - `{oid}` {head}")
+            if _commit_lines:
+              _commit_blocks.append(
+                f"**[#{pr['number']}]({pr['url']}) {pr['title']}**\n" + "\n".join(_commit_lines)
+              )
+          # Fall back to the raw git log only when no PR commits are available.
+          commits_section = "\n\n".join(_commit_blocks) if _commit_blocks else commits
           if filtered:
             prs_lines = "\n".join(_pr_entry(pr) for pr in filtered)
             seen, clabels = set(), []
@@ -508,7 +560,7 @@ jobs:
             "Happy Training!\n\n"
             "---\n\n"
             "### What's Changed precisely:\n\n"
-            f"{commits}\n\n"
+            f"{commits_section}\n\n"
             "---\n\n"
             "### Thank you!\n\n"
             f"{contributors}\n"

weightslab-1.3.0/AGENTS.md

@@ -0,0 +1,275 @@
+# WeightsLab — agent context for users & debugging
+
+This file is a **portable context for AI coding agents** (Claude Code, etc.) and
+the humans driving them. Its job is to let you — or an agent helping you —
+**install, configure, run, and debug WeightsLab and Weights Studio** without
+having to reverse-engineer the system first.
+
+It deliberately covers only the two shipped repositories:
+
+- **weightslab** — the Python backend / core (training instrumentation, data
+  ledger, gRPC service, the shared proto).
+- **weights_studio** — the browser frontend (the studio UI that inspects and
+  edits a *running* experiment).
+
+> File/line references drift as the code evolves — treat them as starting points
+> and verify against the current source before relying on them. Environment
+> variable names and defaults are the most stable thing here; when in doubt the
+> authoritative reference is `weightslab/docs/configuration.rst`.
+
+---
+
+## 0. How to load this guide into Claude Code
+
+So an agent actually *has* this context when you ask it for help:
+
+- **Working inside a checkout of the repo** (`git clone`): this guide is
+  committed as `AGENTS.md`; the repo keeps a gitignored `CLAUDE.md` copy of it at
+  the root so Claude Code auto-loads it every session. Nothing to do. (Claude
+  Code also loads `~/.claude/CLAUDE.md` global memory and any parent-dir
+  `CLAUDE.md`.)
+- **You only ran `pip install weightslab`** (no checkout — the package lives in
+  `site-packages`): absolute `@import` paths are fragile because the path
+  changes per venv/OS. The robust pattern is a small **skill** that locates the
+  installed file at runtime. Create `~/.claude/skills/weightslab/SKILL.md`:
+
+  ```yaml
+  ---
+  name: weightslab
+  description: Load the WeightsLab debugging & configuration guide when helping with weightslab or weights_studio problems (connection, TLS, env vars, training hangs, rendering).
+  ---
+  !`python -c "import weightslab, os; print(open(os.path.join(os.path.dirname(weightslab.__file__), 'AGENTS.md')).read())"`
+
+  Use the guide above to diagnose the user's weightslab / weights_studio issue.
+  ```
+
+  Then run `/weightslab` (or let Claude auto-invoke it). This requires the guide
+  to be **shipped as package data** inside the installed package (see §7); the
+  copy at the repo root is for contributors working in a checkout.
+- **Quick-and-dirty:** copy this file to `~/.claude/WEIGHTSLAB.md` and add
+  `@~/.claude/WEIGHTSLAB.md` to your `~/.claude/CLAUDE.md`.
+
+---
+
+## 1. What it is and how the pieces connect
+
+A user wraps their own PyTorch training script with WeightsLab so a running
+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
+```
+
+- 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.
+- The gRPC servicer and the training loop run in the **same process, different
+  threads**, coordinated by locks in
+  `weightslab/weightslab/components/global_monitoring.py`.
+- One proto is the single source of truth:
+  `weightslab/weightslab/proto/experiment_service.proto`.
+
+---
+
+## 2. Install & run (the happy path)
+
+```bash
+pip install weightslab
+```
+
+In your training script:
+
+```python
+import weightslab as wl
+# wrap your objects so the studio can see/edit them (see §3), then:
+wl.serve(serving_grpc=True, serving_cli=True)   # background threads, same process
+# ... your training loop ...
+wl.keep_serving()                                # keep the process alive for the UI
+```
+
+Then start the studio stack (Envoy + frontend) and open it in a browser.
+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`.
+
+---
+
+## 3. The integration API (`import weightslab as wl`)
+
+How a user's script plugs in. Wrap each training object with
+`wl.watch_or_edit(obj, flag=...)`; the returned tracked proxy is registered in
+the global ledger (`weightslab/weightslab/backend/ledgers.py`,
+`GLOBAL_LEDGER` — the hub everything reads/mutates through).
+
+- `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 that matter for correctness:
+
+- 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 — **skip it and pause/resume or stats will misbehave.**
+- Use `model.get_age()` (steps actually trained; survives checkpoint reloads),
+  not the raw loop counter.
+- `task_type` on the dataset/model selects rendering: `classification`,
+  `segmentation`, `detection`, `detection_pointcloud`.
+- **Hyperparameter handle access:** the registered hyperparameters proxy
+  supports both `hp.get("lr")` and `hp["lr"]` (subscript == `.get`), and stays
+  live — reads reflect in-place updates and re-registration.
+
+---
+
+## 4. Configuration (environment variables)
+
+WeightsLab and Weights Studio are configured almost entirely through env vars.
+**Authoritative reference: `weightslab/docs/configuration.rst`.** The high-signal
+ones when debugging:
+
+**Backend (Python):**
+
+| 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_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). |
+| `GRPC_WATCHDOG_STUCK_SECONDS` | `60` | Lock/RPC stuck threshold + lock-acquire timeout. |
+
+**Frontend (Weights Studio) — runtime-injected `window.*` globals:**
+
+| 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_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. |
+| `ENABLE_PLOTS` | `1` | `0`/`false` removes the plots board + Signals card and stops plot auto-refresh. |
+| `ENABLE_DATA_EXPLORATION` | `1` | `0`/`false` removes the data grid + metadata/details panel and stops the data/metadata auto-refresh. |
+| `ENABLE_HYPERPARAMETERS_OPTIMIZATION` | `1` | `0`/`false` removes the Hyperparameters section, makes HP inputs read-only, and stops the HP poll. |
+| `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:
+> `weightslab/docs/configuration.rst` (“Feature toggles”).
+
+---
+
+## 5. Troubleshooting — symptom → cause → fix
+
+This is the core of the guide. Each entry is a real failure mode (several are
+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`).
+
+**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.
+
+**Sample grid flashes empty cells when auto-refresh fires.**
+An auto-refresh (timer or manual) that lands while a `GetDataSamples` grid fetch
+is still in flight used to clear the cache mid-render. The fix in
+`weights_studio/src/grid_data/gridDataManager.ts` is `isFetchInProgress()`:
+refreshes are skipped while a grid fetch is ongoing. If you see this, confirm
+you're on a build that has that guard.
+
+**Detection overlays are slow or unreadably cluttered.**
+Dense detection samples can carry hundreds of boxes. Cap rendering with
+`BB_THUMB_RENDER` (thumbnails) and `BB_MODAL_RENDER` (modal); each is applied
+separately to GT and to predictions. Render-only — no sample data is dropped.
+
+**Training appears hung; RPCs return `RESOURCE_EXHAUSTED`; server "restarts".**
+A watchdog monitors the global rlock and in-flight RPCs. If a lock/RPC is held
+longer than `GRPC_WATCHDOG_STUCK_SECONDS` (60s) it's flagged; locks get
+interrupted, and after `GRPC_WATCHDOG_RESTART_THRESHOLD` unhealthy polls the
+gRPC server restarts. When **debugging with breakpoints** that intentionally
+pause longer than that, set `WEIGHTSLAB_DISABLE_WATCHDOGS=1`. If RPCs fail with
+`RESOURCE_EXHAUSTED`, a handler couldn't acquire the lock within the window —
+something else is holding it; check for a long/blocking train or eval step.
+
+**Pause/resume doesn't work, or train vs test stats are mixed up.**
+The train step isn't wrapped in `guard_training_context` (or eval in
+`guard_testing_context`). See §3 — these context managers are how the system
+gates and separates phases.
+
+**Large weights/images fail to transfer.** Raise `GRPC_MAX_MESSAGE_BYTES`.
+
+**The agent bar says it's unconfigured.** The LLM agent needs a provider: a
+local **Ollama** server (`provider: ollama`, available immediately) or **cloud
+OpenRouter** initialized from the UI via `/init` (then `/model` to switch,
+`/reset` to clear). See `weightslab/docs/weights_studio.rst`.
+
+---
+
+## 6. Where things live (for deeper digging)
+
+**Backend (`weightslab/weightslab/`):**
+- `src.py` — the public verbs (`watch_or_edit`, `serve`, `keep_serving`,
+  `tag_samples`, `query_*`, decorators) re-exported from `__init__.py`.
+- `trainer/services/` — `experiment_service.py` (gRPC servicer) delegating to
+  `{model,data,agent}_service.py`; `data_image_utils.py` (preview/mask encoding).
+- `components/` — `global_monitoring.py` (locks, `guard_*` contexts, pause),
+  `checkpoint_manager.py`, `evaluation_controller.py`.
+- `data/` — `dataframe_manager.py`, `data_samples_with_ops.py`, `sample_stats.py`,
+  H5 storage (`h5_dataframe_store.py`, `h5_array_store.py`, `array_proxy.py`).
+- `backend/` — `ledgers.py` (`GLOBAL_LEDGER`), `logger.py`, `audit_logger.py`, `cli.py`.
+- `security/` (`CertAuthManager`), `proto/`, `examples/`, `docs/`.
+
+**Frontend (`weights_studio/src/`):**
+- `main.ts` — bootstrap; builds the grpc-web transport from `WS_SERVER_*`.
+- `experiment_service.client.ts` / `experiment_service.ts` — generated client
+  (regenerate with `npm run generate-proto:data`; do not hand-edit).
+- `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.
+
+**Docs:** `weightslab/docs/` (Sphinx) — `configuration.rst` (all env vars),
+`weights_studio.rst` (studio deploy + agent), `quickstart.rst`, `grpc/`.
+
+---
+
+## 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.
+- **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
+  the build broken.
+- **Tests:** backend `python -m pytest weightslab/tests/...`; frontend unit
+  `npm run test` (vitest); E2E/user-simulation Playwright lives in
+  **weights_studio** (`test:realtime:*`, `test:e2e:*`), not here.
+- **CI on a custom branch:** pushes to non-`main`/`dev` branches only run CI when
+  the commit message contains `[force ci]` (both repos).
+- **TLS/auth in the bundled UI** is decided by cert presence under
+  `WEIGHTSLAB_CERTS_DIR` (single source of truth) — don't hardcode secure/insecure.
+- **To make this guide available to pip users**, ship it as package data inside
+  the installed package (e.g. as `weightslab/weightslab/AGENTS.md`) so the §0
+  skill can locate it; keep the root `AGENTS.md` (mirrored as the gitignored
+  `CLAUDE.md`) as the contributor-facing source.

weightslab-1.3.0/CHANGELOG.md

@@ -0,0 +1 @@
+# Changelog - 2026-06-26 v1.3.0 (1)