v2.0 Weightslab

.gitignore

@@ -8,6 +8,8 @@ agents
 dist
 static
 weightslab/ui/static/
+weightslab/**/AGENTS.md
+weightslab/**/opencode.json
 
 # Ignore files and directories generated by Python
 logs
@@ -49,9 +51,10 @@ htmlcov-report
 experiment_service_pb2.py
 experiment_service_pb2_grpc.py
 settings.json
-laumch.json
+launch.json
 pkg_main.py
 _version.py
+.wl_opencode.json
 
 # Ignore extensions
 *.onnx

AGENTS.md

@@ -132,6 +132,37 @@ Conventions that matter for correctness:
   supports both `hp.get("lr")` and `hp["lr"]` (subscript == `.get`), and stays
   live — reads reflect in-place updates and re-registration.
 
+Recording values (pick by what the value is *about*, not by convenience):
+
+| Value describes | Verb | Example |
+|---|---|---|
+| one sample | `wl.save_signals(signals={...}, batch_ids=ids, ...)` | an image's loss |
+| one annotation | `wl.save_instance_signals(...)` | one box's IoU |
+| a group of samples | `wl.save_group_signals(signals={...}, group_ids=[...])` | a pair's contrastive loss |
+| one training **step** | `wl.save_model_signals(signals={...})` | a gradient norm |
+
+The first three write dataframe rows (sortable/filterable in the grid); the
+fourth only plots a curve. Never fake a step-level value by broadcasting it
+across `batch_ids` — that writes a number onto samples it was never about.
+
+- **Training-dynamics signals** come free with
+  `wl.watch_or_edit(model, flag="model", track_model_signals=True,
+  model_signals_every_n_steps=N)`. That emits, per step and with no call in the
+  training loop: `metrics/global/{grad_norm,weights_norm}` and
+  `metrics/layer/<layer_id>/{grad_norm,weights_norm,activation_mean,
+  activation_std,activation_max,activation_min}`. `<layer_id>` is the same id
+  architecture ops (freeze/reset) address, so a bad curve names the layer to act
+  on. Only collects inside `guard_training_context`, so eval never contaminates
+  it. Implementation: `weightslab/weightslab/components/model_signals.py`;
+  example: `examples/Usecases/wl-fashion-mnist-signals`.
+  - Diagnosing from these: early-layer `grad_norm` → 0 with healthy late layers
+    = vanishing gradient; `grad_norm` spiking orders of magnitude = exploding;
+    `activation_std` → 0 on a layer = that layer went constant (dead
+    ReLU/saturated BN); `weights_norm` growing while loss flattens = needs decay.
+  - Per-layer curves need per-layer modules: an `nn.Sequential` block resolves
+    to ONE layer id, so a model built out of Sequentials gets one curve for the
+    whole block.
+
 ---
 
 ## 4. Configuration (environment variables)

README.md

@@ -319,6 +319,20 @@ Find our documentation [online](https://grayboxtech.github.io/weightslab/latest/
 
 </details>
 
+<details>
+<summary><b>Agent: chat with your training run (OpenCode)</b></summary>
+
+<br>
+
+WeightsLab ships two distinct agent surfaces — the backend SDK agent for data-manipulation
+queries, and a local [OpenCode](https://opencode.ai)-backed agent with a full bash/file
+toolset that can restart training, edit your code, and run recurring `/loop` monitoring
+jobs. See the [Agent docs](https://grayboxtech.github.io/weightslab/latest/agent.html) for
+how the two connect, how to point either one at a local model, and the full `/loop`
+reference.
+
+</details>
+
 </details>
 
 <details>

agent_config.yaml

@@ -4,25 +4,20 @@
 # or directly in the config file.
 # Config file values will override env. variables if both are set.
 # If cloned, env. variables can be defined in a .env file at the root of the repository.
+#
+# OpenCode (opencode.ai) is the only supported agent backend: a local OpenCode
+# server backs every LLM call. There is no API key here -- the credential
+# lives in OpenCode's own config, entered once via `opencode auth login` or
+# the Weights Studio landing page's login modal.
 agent:
-  # Select the model provider.
-  # Local: 'ollama'
-  # Remote: 'openrouter'
-  # provider: openrouter  # Default to OpenRouter if API key is provided, otherwise fallback to local Ollama. This can be overridden by env variable PREFERRED_PROVIDER.
+  # URL of the local OpenCode server (can also be set as env variable
+  # OPENCODE_URL). Defaults to http://127.0.0.1:4096. This is the SAME shared
+  # root env var the frontend reads, so set it once and both sides point at
+  # one server.
+  opencode_url: http://127.0.0.1:4096
 
-  # Local Settings
-  fallback_to_local: false
-  ollama_model: llama3.2:3b
-
-  # # Remote Model Selection
-  # Default is a fast flash-class model. The intent-planning task is simple JSON
-  # generation, so a small/fast model responds in ~2-4s where a 70B model took
-  # ~15-30s for no accuracy gain. Switch back to a large model here if you see
-  # accuracy issues (speed/accuracy tradeoff).
-  openrouter_model: bytedance-seed/seed-2.0-lite  # Open router model name (can also be set as env variable OPENROUTER_MODEL). Fast alternatives: openai/gpt-4o-mini, meta-llama/llama-3.1-8b-instruct. Accurate/slow: ~google/gemini-flash-latest
-  # openrouter_api_key: <your_openrouter_api_key>  # Open router API key (can also be set as env variable OPENROUTER_API_KEY)
-  openrouter_base_url: https://openrouter.ai/api/v1  # Open router base URL (can also be set as env variable OPENROUTER_BASE_URL)
-  openrouter_request_timeout: 60.0  # Timeout for OpenRouter API requests in seconds (can also be set as env variable OPENROUTER_REQUEST_TIMEOUT)
-  openrouter_max_tokens: 2048  # Max completion length. OpenRouter reserves max_tokens*price against the key budget BEFORE generating, so an uncapped value can 402 ("more credits, or fewer max_tokens") on a credit/weekly-limited key. Raise only if responses get truncated (env: OPENROUTER_MAX_TOKENS)
-  openrouter_provider_sort: throughput  # Bias OpenRouter's upstream routing to avoid slow providers: 'throughput' | 'latency' | 'price'. Empty string = let OpenRouter choose (env: OPENROUTER_PROVIDER_SORT)
-  openrouter_structured_output: false  # Ask the model for a schema-validated plan directly (skips free-form JSON + regex repair). More reliable, but only works on models whose OpenRouter route supports structured/JSON-schema output (e.g. Gemini, GPT-4o). env: OPENROUTER_STRUCTURED_OUTPUT=1
+  # OpenCode model, "providerID/modelID" (can also be set as env variable
+  # OPENCODE_MODEL). Empty string self-heals to whatever OpenCode's own
+  # config was last set to, or a configured provider default, falling back
+  # to the free-tier "opencode/deepseek-v4-flash-free" if neither resolves.
+  opencode_model: "opencode/deepseek-v4-flash-free"

docs/_scripts/update_whats_new.py

@@ -0,0 +1,254 @@
+#!/usr/bin/env python3
+"""Regenerate ``docs/whats_new.rst`` from the repository's GitHub releases.
+
+The page is committed as static RST rather than fetched while Sphinx runs: a
+docs build that reached out to api.github.com would fail on an offline machine,
+in an air-gapped CI runner, or simply when the unauthenticated rate limit is
+spent -- and it would fail at the moment someone is trying to build the docs,
+which is the worst time to discover it. Regenerating is a deliberate step::
+
+    python docs/_scripts/update_whats_new.py
+
+Only **stable** releases are listed. Every tag push also publishes a
+``vX.Y.Z.devN`` pre-release to TestPyPI for verification (see ci.yml's
+``build-and-publish-dev-release``), and those outnumber the real releases
+roughly two to one -- a "What's New" page carrying them would be mostly noise
+about build plumbing.
+
+Each summary is the release body **between the "Welcome" heading and the
+"What's Changed precisely:" heading**, which is where the release template puts
+the human description. Two transformations make that readable:
+
+* the boilerplate wrapping it (identical in all ten releases) is stripped;
+* the template flattens every PR description onto a single line, so the
+  structure it had as markdown survives only as inline ``" - "`` separators and
+  stray ``"## Heading"`` markers -- ``_description_lines`` recovers it as real
+  nested bullets. Without that step the page is ten paragraphs of run-on text.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import urllib.request
+from datetime import datetime, timezone
+from pathlib import Path
+
+REPO = "GrayboxTech/weightslab"
+RELEASE_COUNT = 10
+OUTPUT = Path(__file__).resolve().parents[1] / "whats_new.rst"
+
+LEAD_IN = re.compile(
+    r"^Welcome to the \*\*[^*]+\*\* release of WeightsLab\.[^\n]*\n+", re.M)
+TAIL = re.compile(r"\n*One platform\. Unmatched flexibility\..*\Z", re.S)
+
+SECTION_MARKER = re.compile(r"\s*#{2,4}\s+([A-Z][^#\n]{0,40}?)\s+(?=[-*`\[A-Z])")
+ITEM_SPLIT = re.compile(r"\s+-\s+(?=[\[`*\w])")
+PR_BULLET = re.compile(r"^\[([^\]]+)\]\(([^)]+)\)\s*:?\s*(.*)$", re.S)
+
+
+def fetch_releases() -> list:
+    releases, page = [], 1
+    while True:
+        url = f"https://api.github.com/repos/{REPO}/releases?per_page=100&page={page}"
+        req = urllib.request.Request(url, headers={"Accept": "application/vnd.github+json"})
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            batch = json.load(resp)
+        releases += batch
+        if len(batch) < 100:
+            return releases
+        page += 1
+
+
+def stable_releases(releases: list) -> list:
+    out = [r for r in releases if not r.get("prerelease") and not r.get("draft")]
+    out.sort(key=lambda r: r.get("published_at") or "", reverse=True)
+    return out[:RELEASE_COUNT]
+
+
+def welcome_section(body: str) -> str:
+    match = re.search(
+        r"^#{1,4}\s*Welcome\s*$(.*?)^#{1,4}\s*What's Changed", body or "", re.M | re.S)
+    return (match.group(1) if match else "").strip()
+
+
+def _strip_boilerplate(text: str) -> str:
+    return TAIL.sub("", LEAD_IN.sub("", text)).strip()
+
+
+def md_inline_to_rst(text: str) -> str:
+    """Convert the inline markdown that turns up in PR descriptions.
+
+    Deliberately small: these are PR descriptions pasted into a release
+    template, so they carry links, bold, and inline code and little else.
+    """
+    text = re.sub(r"`([^`]+)`", r"``\1``", text)
+    text = re.sub(r"\[([^\]]+)\]\(([^)]+)\)", r"`\1 <\2>`__", text)
+    text = re.sub(r"_\(([^)]+)\)_", r"*(\1)*", text)
+    text = re.sub(r"\s{2,}", " ", text)
+    return text.strip()
+
+
+def _sanitize(text: str) -> str:
+    """Repair the two things the release template's flattening leaves behind.
+
+    A GitHub task-list marker (``[ ]``) carries no meaning once the checklist
+    has been flattened into prose, and an unbalanced backtick is an outright
+    RST error -- which happens whenever the template truncates a long PR body
+    mid-token, as it does with an ellipsis. Closing the text at the last
+    balanced point is honest about the truncation and keeps the build clean;
+    the card links to the full release notes anyway.
+    """
+    text = re.sub(r"^[-*]\s+", "", text.strip())
+    text = re.sub(r"^\[[ xX]\]\s*", "", text)
+    for marker in ("`", "**"):
+        if text.count(marker) % 2:
+            text = text[:text.rindex(marker)].rstrip(" .") + " …"
+    return text.strip()
+
+
+def _wrap(text: str, width: int, first: str, rest: str) -> list:
+    """Greedy wrap that keeps an RST bullet or indent prefix on the first line."""
+    words = text.split()
+    if not words:
+        return []
+    out, line = [], first + words[0]
+    for word in words[1:]:
+        if len(line) + 1 + len(word) > width:
+            out.append(line)
+            line = rest + word
+        else:
+            line += " " + word
+    out.append(line)
+    return out
+
+
+def _description_lines(description: str, indent: str) -> list:
+    """Render one PR's flattened description as nested RST beneath its bullet."""
+    if not description.strip():
+        return []
+
+    marked = SECTION_MARKER.sub(
+        lambda m: "\n@@" + m.group(1).rstrip(":") + "@@\n", description)
+
+    lines = []
+    for block in marked.split("\n"):
+        block = block.strip()
+        if not block:
+            continue
+        heading = re.fullmatch(r"@@(.+)@@", block)
+        if heading:
+            lines.append("")
+            lines.append(indent + "**" + md_inline_to_rst(heading.group(1)) + "**")
+            continue
+        items = [i.strip() for i in ITEM_SPLIT.split(block) if i.strip()]
+        lines.append("")
+        if len(items) > 1:
+            for item in items:
+                lines.extend(_wrap(_sanitize(md_inline_to_rst(item)), 86,
+                                   first=indent + "- ", rest=indent + "  "))
+        else:
+            lines.extend(_wrap(_sanitize(md_inline_to_rst(items[0])), 86,
+                               first=indent, rest=indent))
+    return lines
+
+
+def summary_to_rst(body: str) -> list:
+    text = _strip_boilerplate(welcome_section(body))
+    if not text:
+        return ["   *No description was published with this release.*"]
+
+    lines, entries, current = [], [], None
+    for raw in text.splitlines():
+        stripped = raw.strip()
+        if not stripped or stripped == "---":
+            continue
+        if stripped.startswith("- "):
+            current = [stripped[2:]]
+            entries.append(current)
+        elif stripped.startswith(">") and current is not None:
+            current.append(stripped.lstrip("> ").strip())
+        elif current is not None:
+            current.append(stripped)
+        else:
+            lines.extend(_wrap(_sanitize(md_inline_to_rst(stripped)), 86, first="   ", rest="   "))
+
+    for entry in entries:
+        joined = " ".join(entry).strip()
+        match = PR_BULLET.match(joined)
+        if match:
+            label, url, description = match.groups()
+            lines.append("   - `" + label.strip() + " <" + url.strip() + ">`__")
+            lines.extend(_description_lines(description, "     "))
+        else:
+            lines.extend(_wrap(_sanitize(md_inline_to_rst(joined)), 86, first="   - ", rest="     "))
+        lines.append("")
+
+    while lines and not lines[-1].strip():
+        lines.pop()
+    return lines
+
+
+HEADER = """.. _whats-new:
+
+What's New
+==========
+
+The last {count} stable releases of WeightsLab, newest first. Each card links to
+its full release notes on GitHub, where the complete "What's Changed" commit
+list lives.
+
+.. note::
+
+   Only stable releases appear here. Every tag also publishes a
+   ``vX.Y.Z.devN`` pre-release to TestPyPI for verification; those are build
+   plumbing rather than user-facing changes.
+
+.. tip::
+
+   Upgrade with ``pip install --upgrade weightslab``. Setting up for the first
+   time? Start at :doc:`quickstart`.
+
+"""
+
+FOOTER = """
+----
+
+`Every release on GitHub → <https://github.com/{repo}/releases>`__
+
+.. This page is generated. To refresh it after a release:
+..     python docs/_scripts/update_whats_new.py
+.. Last generated: {generated}
+"""
+
+
+def build_rst(releases: list) -> str:
+    parts = [HEADER.format(count=len(releases))]
+    for release in releases:
+        published = datetime.fromisoformat(
+            release["published_at"].replace("Z", "+00:00")).astimezone(timezone.utc)
+        date_label = f"{published.strftime('%B')} {published.day}, {published.year}"
+
+        parts.append(".. card::\n")
+        parts.append(f"   :link: {release['html_url']}\n")
+        parts.append("   :class-card: wl-release-card\n\n")
+        parts.append("   .. rst-class:: wl-release-date\n\n")
+        parts.append(f"   {date_label}\n\n")
+        parts.append("   .. rst-class:: wl-release-version\n\n")
+        parts.append(f"   {release['tag_name']}\n\n")
+        parts.append("\n".join(summary_to_rst(release.get("body") or "")))
+        parts.append("\n\n")
+    parts.append(FOOTER.format(
+        repo=REPO, generated=datetime.now(timezone.utc).strftime("%Y-%m-%d")))
+    return "".join(parts)
+
+
+def main() -> None:
+    releases = stable_releases(fetch_releases())
+    OUTPUT.write_text(build_rst(releases), encoding="utf-8")
+    print(f"wrote {OUTPUT} — {len(releases)} releases, "
+          f"{releases[-1]['tag_name']} … {releases[0]['tag_name']}")
+
+
+if __name__ == "__main__":
+    main()